v2.8.0

The OCI handler had /v2/ baked into all regex patterns and Location headers.
When basePath was set to /v2 (as in stack.gallery), stripping it removed the
prefix that patterns expected, causing all OCI endpoints to 404.

Now patterns match on bare paths after basePath stripping, working correctly
regardless of the basePath value.

Also adds configurable apiPrefix to OCI upstream class (default /v2) for
registries behind reverse proxies with custom path prefixes.

.smartconfig.json

@@ -0,0 +1,24 @@
+{
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
+      "gitrepo": "smartregistry",
+      "description": "A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries",
+      "npmPackagename": "@push.rocks/smartregistry",
+      "license": "MIT",
+      "projectDomain": "push.rocks"
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
+    }
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
+  }
+}

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "json.schemas": [
     {
-      "fileMatch": ["/npmextra.json"],
+      "fileMatch": ["/.smartconfig.json"],
       "schema": {
         "type": "object",
         "properties": {

changelog.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 2026-03-24 - 2.8.0 - feat(core,storage,oci,registry-config)
+add streaming response support and configurable registry URLs across protocols
+
+- Normalize SmartRegistry responses to ReadableStream bodies at the public API boundary and add stream helper utilities for buffers, JSON, and hashing
+- Add streaming storage accessors for OCI, npm, Maven, Cargo, Composer, PyPI, and RubyGems downloads to reduce in-memory buffering
+- Make per-protocol registryUrl configurable so CLI and integration tests can use correct host and port values
+- Refactor OCI blob uploads to persist chunks in storage during upload and clean up temporary chunk objects after completion or expiry
+- Update tests and storage integration to use the new stream-based response model and smartstorage backend
+
+## 2025-12-03 - 2.7.0 - feat(upstream)
+Add dynamic per-request upstream provider and integrate into registries
+
+- Introduce IUpstreamProvider and IUpstreamResolutionContext to resolve upstream configs per request.
+- Add StaticUpstreamProvider implementation for simple static upstream configurations.
+- Propagate dynamic upstream provider through SmartRegistry and wire into protocol handlers (npm, oci, maven, cargo, composer, pypi, rubygems).
+- Replace persistent per-protocol upstream instances with per-request resolution: registries now call provider.resolveUpstreamConfig(...) and instantiate protocol-specific Upstream when needed.
+- Add IRequestActor to core interfaces and pass actor context (userId, ip, userAgent, etc.) to upstream resolution and storage/auth hooks.
+- Update many protocol registries to accept an upstreamProvider instead of IProtocolUpstreamConfig and to attempt upstream fetches only when provider returns enabled config.
+- Add utilities and tests: test helpers to create registries with upstream provider, a tracking upstream provider helper, StaticUpstreamProvider tests and extensive upstream/provider integration tests.
+- Improve upstream interfaces and cache/fetch contexts (IUpstreamFetchContext includes actor) and add StaticUpstreamProvider class to upstream module.
+
+## 2025-11-27 - 2.6.0 - feat(core)
+Add core registry infrastructure: storage, auth, upstream cache, and protocol handlers
+
+- Introduce RegistryStorage: unified storage abstraction with hook support (before/after put/delete/get) and helpers for OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems paths and operations
+- Add DefaultAuthProvider and AuthManager: in-memory token store, UUID tokens for package protocols, OCI JWT creation/validation, token lifecycle (create/validate/revoke) and authorization checking
+- Add SmartRegistry orchestrator to initialize and route requests to protocol handlers (OCI, NPM, Maven, Cargo, Composer, PyPI, RubyGems)
+- Implement upstream subsystem: UpstreamCache (in-memory + optional S3 persistence), BaseUpstream with multi-upstream routing, scope rules, retries, TTLs, stale-while-revalidate and negative caching
+- Add circuit breaker implementation for upstream resilience with exponential backoff and per-upstream breakers
+- Add protocol implementations and helpers: NpmRegistry/NpmUpstream (packument/tarball handling and tarball URL rewriting), PypiRegistry (PEP 503/691 support, uploads, metadata), MavenRegistry (artifact/metadata handling and checksum generation), CargoRegistry (sparse index, publish/download/yank)
+- Utility exports and helpers: buffer helpers, plugins aggregator, path helpers, and various protocol-specific helper modules
+
+## 2025-11-27 - 2.5.0 - feat(pypi,rubygems)
+Add PyPI and RubyGems protocol implementations, upstream caching, and auth/storage improvements
+
+- Implemented full PyPI support (PEP 503 Simple API HTML, PEP 691 JSON API, legacy upload handling, name normalization, hash verification, content negotiation, package/file storage and metadata management).
+- Implemented RubyGems support (compact index, /versions, /info, /names endpoints, gem upload, yank/unyank, platform handling and file storage).
+- Expanded RegistryStorage with protocol-specific helpers for OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems (get/put/delete/list helpers, metadata handling, context-aware hooks).
+- Added AuthManager and DefaultAuthProvider improvements: unified token creation/validation for multiple protocols (npm, oci, maven, composer, cargo, pypi, rubygems) and OCI JWT support.
+- Added upstream infrastructure: BaseUpstream, UpstreamCache (S3-backed optional, stale-while-revalidate, negative caching), circuit breaker with retries/backoff and resilience defaults.
+- Added various protocol registries (NPM, Maven, Cargo, OCI, PyPI) with request routing, permission checks, and optional upstream proxying/caching.
+
+## 2025-11-27 - 2.4.0 - feat(core)
+Add pluggable auth providers, storage hooks, multi-upstream cache awareness, and PyPI/RubyGems protocol implementations
+
+- Introduce pluggable authentication: IAuthProvider interface and DefaultAuthProvider (in-memory) with OCI JWT support and UUID tokens.
+- AuthManager now accepts a custom provider and delegates all auth operations (authenticate, validateToken, create/revoke tokens, authorize, listUserTokens).
+- Add storage hooks (IStorageHooks) and hook contexts: beforePut/afterPut/afterGet/beforeDelete/afterDelete. RegistryStorage now supports hooks, context management (setContext/withContext) and invokes hooks around operations.
+- RegistryStorage expanded with many protocol-specific helper methods (OCI, NPM, Maven, Cargo, Composer, PyPI, RubyGems) and improved S3/SmartBucket integration.
+- Upstream improvements: BaseUpstream and UpstreamCache became multi-upstream aware (cache keys now include upstream URL), cache operations are async and support negative caching, stale-while-revalidate, ETag/metadata persistence, and S3-backed storage layer.
+- Circuit breaker, retry, resilience and scope-rule routing enhancements for upstreams; upstream fetch logic updated to prefer primary upstream for cache keys and background revalidation behavior.
+- SmartRegistry API extended to accept custom authProvider and storageHooks, and now wires RegistryStorage and AuthManager with those options. Core exports updated to expose auth and storage interfaces and DefaultAuthProvider.
+- Add full PyPI (PEP 503/691, upload API) and RubyGems (Compact Index, API v1, uploads/yank/unyank, specs endpoints) registry implementations with parsing, upload/download, metadata management and upstream proxying.
+- Add utility helpers: binary buffer helpers (toBuffer/isBinaryData), pypi and rubygems helper modules, and numerous protocol-specific helpers and tests referenced in readme.hints.
+- These changes are additive and designed to be backward compatible; bumping minor version.
+
+## 2025-11-27 - 2.3.0 - feat(upstream)
+Add upstream proxy/cache subsystem and integrate per-protocol upstreams
+
+- Introduce a complete upstream subsystem (BaseUpstream, UpstreamCache, CircuitBreaker) with caching, negative-cache, stale-while-revalidate, retries, exponential backoff and per-upstream circuit breakers.
+- Add upstream interfaces and defaults (ts/upstream/interfaces.upstream.ts) and export upstream utilities from ts/upstream/index.ts and root ts/index.ts.
+- Implement protocol-specific upstream clients for npm, pypi, maven, composer, cargo and rubygems (classes.*upstream.ts) to fetch metadata and artifacts from configured upstream registries.
+- Integrate upstream usage into registries: registries now accept an upstream config, attempt to fetch missing metadata/artifacts from upstreams, cache results locally, and expose destroy() to stop upstream resources.
+- Add SmartRequest and minimatch to dependencies and expose smartrequest/minimatch via ts/plugins.ts for HTTP requests and glob-based scope matching.
+- Update package.json to add @push.rocks/smartrequest and minimatch dependencies.
+- Various registry implementations updated to utilize upstreams (npm, pypi, maven, composer, cargo, rubygems, oci) including URL rewrites and caching behavior.
+
+## 2025-11-27 - 2.2.3 - fix(tests)
+Use unique test run IDs and add S3 cleanup in test helpers to avoid cross-run conflicts
+
+- Add generateTestRunId() helper in test/helpers/registry.ts to produce unique IDs for each test run
+- Update PyPI and Composer native CLI tests to use generated testPackageName / unauth-pkg-<id> to avoid package name collisions between runs
+- Import smartbucket and add S3 bucket cleanup logic in test helpers to remove leftover objects between test runs
+- Improve test robustness by skipping upload-dependent checks when tools (twine/composer) are not available and logging outputs for debugging
+
+## 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
 

npmextra.json

@@ -1,18 +0,0 @@
-{
-  "gitzone": {
-    "projectType": "npm",
-    "module": {
-      "githost": "code.foss.global",
-      "gitscope": "push.rocks",
-      "gitrepo": "smartregistry",
-      "description": "a registry for npm modules and oci images",
-      "npmPackagename": "@push.rocks/smartregistry",
-      "license": "MIT",
-      "projectDomain": "push.rocks"
-    }
-  },
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  }
-}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartregistry",
-  "version": "2.2.0",
+  "version": "2.8.0",
   "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",
@@ -10,17 +10,17 @@
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/ --verbose --logfile --timeout 240)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "build": "(tsbuild --allowimplicitany)",
     "buildDocs": "(tsdoc)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^3.1.0",
-    "@git.zone/tsbundle": "^2.0.5",
-    "@git.zone/tsrun": "^2.0.0",
-    "@git.zone/tstest": "^3.1.0",
-    "@push.rocks/smartarchive": "^5.0.1",
-    "@push.rocks/smarts3": "^5.1.0",
-    "@types/node": "^24.10.1"
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsbundle": "^2.10.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tstest": "^3.6.0",
+    "@push.rocks/smartarchive": "^5.2.1",
+    "@push.rocks/smartstorage": "^6.3.2",
+    "@types/node": "^25.5.0"
   },
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md"
   ],
   "pnpm": {
@@ -47,11 +47,13 @@
   },
   "dependencies": {
     "@push.rocks/qenv": "^6.1.3",
-    "@push.rocks/smartbucket": "^4.3.0",
-    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartbucket": "^4.5.1",
+    "@push.rocks/smartlog": "^3.2.1",
     "@push.rocks/smartpath": "^6.0.0",
-    "@tsclass/tsclass": "^9.3.0",
-    "adm-zip": "^0.5.10"
+    "@push.rocks/smartrequest": "^5.0.1",
+    "@tsclass/tsclass": "^9.5.0",
+    "adm-zip": "^0.5.16",
+    "minimatch": "^10.2.4"
   },
   "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34"
 }

test/cargo.test.node.ts

@@ -2,6 +2,7 @@ import { tap, expect } from '@git.zone/tstest';
 import { RegistryStorage } from '../ts/core/classes.registrystorage.js';
 import { CargoRegistry } from '../ts/cargo/classes.cargoregistry.js';
 import { AuthManager } from '../ts/core/classes.authmanager.js';
+import { streamToJson } from '../ts/core/helpers.stream.js';
 
 // Test index path calculation
 tap.test('should calculate correct index paths for different crate names', async () => {
@@ -123,9 +124,10 @@ tap.test('should return valid config.json', async () => {
 
   expect(response.status).to.equal(200);
   expect(response.headers['Content-Type']).to.equal('application/json');
-  expect(response.body).to.be.an('object');
-  expect(response.body.dl).to.include('/api/v1/crates/{crate}/{version}/download');
-  expect(response.body.api).to.equal('http://localhost:5000/cargo');
+  const body = await streamToJson(response.body);
+  expect(body).to.be.an('object');
+  expect(body.dl).to.include('/api/v1/crates/{crate}/{version}/download');
+  expect(body.api).to.equal('http://localhost:5000/cargo');
 });
 
 export default tap.start();

test/helpers/registry.ts

@@ -1,15 +1,73 @@
 import * as qenv from '@push.rocks/qenv';
 import * as crypto from 'crypto';
 import * as smartarchive from '@push.rocks/smartarchive';
+import * as smartbucket from '@push.rocks/smartbucket';
 import { SmartRegistry } from '../../ts/classes.smartregistry.js';
-import type { IRegistryConfig } from '../../ts/core/interfaces.core.js';
+import type { IRegistryConfig, IAuthToken, TRegistryProtocol } from '../../ts/core/interfaces.core.js';
+import type { IAuthProvider, ITokenOptions } from '../../ts/core/interfaces.auth.js';
+import type { IStorageHooks, IStorageHookContext, IBeforePutResult, IBeforeDeleteResult } from '../../ts/core/interfaces.storage.js';
+import { StaticUpstreamProvider } from '../../ts/upstream/interfaces.upstream.js';
+import type { IUpstreamProvider, IUpstreamResolutionContext, IProtocolUpstreamConfig } from '../../ts/upstream/interfaces.upstream.js';
 
 const testQenv = new qenv.Qenv('./', './.nogit');
 
+/**
+ * Clean up S3 bucket contents for a fresh test run
+ * @param prefix Optional prefix to delete (e.g., 'cargo/', 'npm/', 'composer/')
+ */
+/**
+ * Generate a unique test run ID for avoiding conflicts between test runs
+ * Uses timestamp + random suffix for uniqueness
+ */
+export function generateTestRunId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 6);
+  return `${timestamp}${random}`;
+}
+
+export async function cleanupS3Bucket(prefix?: string): Promise<void> {
+  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 s3 = new smartbucket.SmartBucket({
+    accessKey: s3AccessKey || 'minioadmin',
+    accessSecret: s3SecretKey || 'minioadmin',
+    endpoint: s3Endpoint || 'localhost',
+    port: parseInt(s3Port || '9000', 10),
+    useSsl: false,
+  });
+
+  try {
+    const bucket = await s3.getBucket('test-registry');
+    if (bucket) {
+      if (prefix) {
+        // Delete only objects with the given prefix
+        const files = await bucket.fastList({ prefix });
+        for (const file of files) {
+          await bucket.fastRemove({ path: file.name });
+        }
+      } else {
+        // Delete all objects in the bucket
+        const files = await bucket.fastList({});
+        for (const file of files) {
+          await bucket.fastRemove({ path: file.name });
+        }
+      }
+    }
+  } catch (error) {
+    // Bucket might not exist yet, that's fine
+    console.log('Cleanup: No bucket to clean or error:', error);
+  }
+}
+
 /**
  * Create a test SmartRegistry instance with all protocols enabled
  */
-export async function createTestRegistry(): Promise<SmartRegistry> {
+export async function createTestRegistry(options?: {
+  registryUrl?: string;
+}): Promise<SmartRegistry> {
   // Read S3 config from env.json
   const s3AccessKey = await testQenv.getEnvVarOnDemand('S3_ACCESSKEY');
   const s3SecretKey = await testQenv.getEnvVarOnDemand('S3_SECRETKEY');
@@ -47,30 +105,37 @@ export async function createTestRegistry(): Promise<SmartRegistry> {
     oci: {
       enabled: true,
       basePath: '/oci',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/oci` } : {}),
     },
     npm: {
       enabled: true,
       basePath: '/npm',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/npm` } : {}),
     },
     maven: {
       enabled: true,
       basePath: '/maven',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/maven` } : {}),
     },
     composer: {
       enabled: true,
       basePath: '/composer',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/composer` } : {}),
     },
     cargo: {
       enabled: true,
       basePath: '/cargo',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/cargo` } : {}),
     },
     pypi: {
       enabled: true,
       basePath: '/pypi',
+      ...(options?.registryUrl ? { registryUrl: options.registryUrl } : {}),
     },
     rubygems: {
       enabled: true,
       basePath: '/rubygems',
+      ...(options?.registryUrl ? { registryUrl: `${options.registryUrl}/rubygems` } : {}),
     },
   };
 
@@ -80,6 +145,89 @@ export async function createTestRegistry(): Promise<SmartRegistry> {
   return registry;
 }
 
+/**
+ * Create a test SmartRegistry instance with upstream provider configured
+ */
+export async function createTestRegistryWithUpstream(
+  upstreamProvider?: IUpstreamProvider
+): Promise<SmartRegistry> {
+  // Read S3 config from env.json
+  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');
+
+  // Default to StaticUpstreamProvider with npm.js configured
+  const defaultProvider = new StaticUpstreamProvider({
+    npm: {
+      enabled: true,
+      upstreams: [{ id: 'npmjs', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+    },
+    oci: {
+      enabled: true,
+      upstreams: [{ id: 'dockerhub', url: 'https://registry-1.docker.io', priority: 1, enabled: true }],
+    },
+  });
+
+  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: 'https://auth.example.com/token',
+        service: 'test-registry',
+      },
+      pypiTokens: { enabled: true },
+      rubygemsTokens: { enabled: true },
+    },
+    upstreamProvider: upstreamProvider || defaultProvider,
+    oci: { enabled: true, basePath: '/oci' },
+    npm: { enabled: true, basePath: '/npm' },
+    maven: { enabled: true, basePath: '/maven' },
+    composer: { enabled: true, basePath: '/composer' },
+    cargo: { enabled: true, basePath: '/cargo' },
+    pypi: { enabled: true, basePath: '/pypi' },
+    rubygems: { enabled: true, basePath: '/rubygems' },
+  };
+
+  const registry = new SmartRegistry(config);
+  await registry.init();
+
+  return registry;
+}
+
+/**
+ * Create a mock upstream provider that tracks all calls for testing
+ */
+export function createTrackingUpstreamProvider(
+  baseConfig?: Partial<Record<TRegistryProtocol, IProtocolUpstreamConfig>>
+): {
+  provider: IUpstreamProvider;
+  calls: IUpstreamResolutionContext[];
+} {
+  const calls: IUpstreamResolutionContext[] = [];
+
+  const provider: IUpstreamProvider = {
+    async resolveUpstreamConfig(context: IUpstreamResolutionContext) {
+      calls.push({ ...context });
+      return baseConfig?.[context.protocol] ?? null;
+    },
+  };
+
+  return { provider, calls };
+}
+
 /**
  * Helper to create test authentication tokens
  */
@@ -302,7 +450,7 @@ class TestClass
     },
   ];
 
-  return zipTools.createZip(entries);
+  return Buffer.from(await zipTools.createZip(entries));
 }
 
 /**
@@ -376,7 +524,7 @@ def hello():
     },
   ];
 
-  return zipTools.createZip(entries);
+  return Buffer.from(await zipTools.createZip(entries));
 }
 
 /**
@@ -437,7 +585,7 @@ def hello():
     },
   ];
 
-  return tarTools.packFilesToTarGz(entries);
+  return Buffer.from(await tarTools.packFilesToTarGz(entries));
 }
 
 /**
@@ -508,7 +656,7 @@ summary: Test gem for SmartRegistry
 test_files: []
 `;
 
-  const metadataGz = await gzipTools.compress(Buffer.from(metadataYaml, 'utf-8'));
+  const metadataGz = Buffer.from(await gzipTools.compress(Buffer.from(metadataYaml, 'utf-8')));
 
   // Create data.tar.gz content
   const libContent = `# ${gemName}
@@ -529,7 +677,7 @@ end
     },
   ];
 
-  const dataTarGz = await tarTools.packFilesToTarGz(dataEntries);
+  const dataTarGz = Buffer.from(await tarTools.packFilesToTarGz(dataEntries));
 
   // Create the outer gem (tar.gz containing metadata.gz and data.tar.gz)
   const gemEntries: smartarchive.IArchiveEntry[] = [
@@ -544,7 +692,7 @@ end
   ];
 
   // RubyGems .gem files are plain tar archives (NOT gzipped), containing metadata.gz and data.tar.gz
-  return tarTools.packFiles(gemEntries);
+  return Buffer.from(await tarTools.packFiles(gemEntries));
 }
 
 /**
@@ -556,3 +704,228 @@ export function calculateRubyGemsChecksums(data: Buffer) {
     sha256: crypto.createHash('sha256').update(data).digest('hex'),
   };
 }
+
+// ============================================================================
+// Enterprise Extensibility Test Helpers
+// ============================================================================
+
+/**
+ * Create a mock auth provider for testing pluggable authentication.
+ * Allows customizing behavior for different test scenarios.
+ */
+export function createMockAuthProvider(overrides?: Partial<IAuthProvider>): IAuthProvider {
+  const tokens = new Map<string, IAuthToken>();
+
+  return {
+    init: async () => {},
+    authenticate: async (credentials) => {
+      // Default: always authenticate successfully
+      return credentials.username;
+    },
+    validateToken: async (token, protocol) => {
+      const stored = tokens.get(token);
+      if (stored && (!protocol || stored.type === protocol)) {
+        return stored;
+      }
+      // Mock token for tests
+      if (token === 'valid-mock-token') {
+        return {
+          type: 'npm' as TRegistryProtocol,
+          userId: 'mock-user',
+          scopes: ['npm:*:*:*'],
+        };
+      }
+      return null;
+    },
+    createToken: async (userId, protocol, options) => {
+      const tokenId = `mock-${protocol}-${Date.now()}`;
+      const authToken: IAuthToken = {
+        type: protocol,
+        userId,
+        scopes: options?.scopes || [`${protocol}:*:*:*`],
+        readonly: options?.readonly,
+        expiresAt: options?.expiresIn ? new Date(Date.now() + options.expiresIn * 1000) : undefined,
+      };
+      tokens.set(tokenId, authToken);
+      return tokenId;
+    },
+    revokeToken: async (token) => {
+      tokens.delete(token);
+    },
+    authorize: async (token, resource, action) => {
+      if (!token) return false;
+      if (token.readonly && ['write', 'push', 'delete'].includes(action)) {
+        return false;
+      }
+      return true;
+    },
+    listUserTokens: async (userId) => {
+      const result: Array<{ key: string; readonly: boolean; created: string; protocol?: TRegistryProtocol }> = [];
+      for (const [key, token] of tokens.entries()) {
+        if (token.userId === userId) {
+          result.push({
+            key: `hash-${key.substring(0, 8)}`,
+            readonly: token.readonly || false,
+            created: new Date().toISOString(),
+            protocol: token.type,
+          });
+        }
+      }
+      return result;
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Create test storage hooks that track all calls.
+ * Useful for verifying hook invocation order and parameters.
+ */
+export function createTrackingHooks(options?: {
+  beforePutAllowed?: boolean;
+  beforeDeleteAllowed?: boolean;
+  throwOnAfterPut?: boolean;
+  throwOnAfterGet?: boolean;
+}): {
+  hooks: IStorageHooks;
+  calls: Array<{ method: string; context: IStorageHookContext; timestamp: number }>;
+} {
+  const calls: Array<{ method: string; context: IStorageHookContext; timestamp: number }> = [];
+
+  return {
+    calls,
+    hooks: {
+      beforePut: async (ctx) => {
+        calls.push({ method: 'beforePut', context: ctx, timestamp: Date.now() });
+        return {
+          allowed: options?.beforePutAllowed !== false,
+          reason: options?.beforePutAllowed === false ? 'Blocked by test' : undefined,
+        };
+      },
+      afterPut: async (ctx) => {
+        calls.push({ method: 'afterPut', context: ctx, timestamp: Date.now() });
+        if (options?.throwOnAfterPut) {
+          throw new Error('Test error in afterPut');
+        }
+      },
+      beforeDelete: async (ctx) => {
+        calls.push({ method: 'beforeDelete', context: ctx, timestamp: Date.now() });
+        return {
+          allowed: options?.beforeDeleteAllowed !== false,
+          reason: options?.beforeDeleteAllowed === false ? 'Blocked by test' : undefined,
+        };
+      },
+      afterDelete: async (ctx) => {
+        calls.push({ method: 'afterDelete', context: ctx, timestamp: Date.now() });
+      },
+      afterGet: async (ctx) => {
+        calls.push({ method: 'afterGet', context: ctx, timestamp: Date.now() });
+        if (options?.throwOnAfterGet) {
+          throw new Error('Test error in afterGet');
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Create a blocking storage hooks implementation for quota testing.
+ */
+export function createQuotaHooks(maxSizeBytes: number): {
+  hooks: IStorageHooks;
+  currentUsage: { bytes: number };
+} {
+  const currentUsage = { bytes: 0 };
+
+  return {
+    currentUsage,
+    hooks: {
+      beforePut: async (ctx) => {
+        const size = ctx.metadata?.size || 0;
+        if (currentUsage.bytes + size > maxSizeBytes) {
+          return { allowed: false, reason: `Quota exceeded: ${currentUsage.bytes + size} > ${maxSizeBytes}` };
+        }
+        return { allowed: true };
+      },
+      afterPut: async (ctx) => {
+        currentUsage.bytes += ctx.metadata?.size || 0;
+      },
+      afterDelete: async (ctx) => {
+        currentUsage.bytes -= ctx.metadata?.size || 0;
+        if (currentUsage.bytes < 0) currentUsage.bytes = 0;
+      },
+    },
+  };
+}
+
+/**
+ * Create a SmartBucket storage backend for upstream cache testing.
+ */
+export async function createTestStorageBackend(): Promise<{
+  storage: {
+    getObject: (key: string) => Promise<Buffer | null>;
+    putObject: (key: string, data: Buffer) => Promise<void>;
+    deleteObject: (key: string) => Promise<void>;
+    listObjects: (prefix: string) => Promise<string[]>;
+  };
+  bucket: smartbucket.Bucket;
+  cleanup: () => Promise<void>;
+}> {
+  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 s3 = new smartbucket.SmartBucket({
+    accessKey: s3AccessKey || 'minioadmin',
+    accessSecret: s3SecretKey || 'minioadmin',
+    endpoint: s3Endpoint || 'localhost',
+    port: parseInt(s3Port || '9000', 10),
+    useSsl: false,
+  });
+
+  const testRunId = generateTestRunId();
+  const bucketName = 'test-cache-' + testRunId.substring(0, 8);
+  const bucket = await s3.createBucket(bucketName);
+
+  const storage = {
+    getObject: async (key: string): Promise<Buffer | null> => {
+      try {
+        const file = await bucket.fastGet({ path: key });
+        if (!file) return null;
+        const stream = await file.createReadStream();
+        const chunks: Buffer[] = [];
+        for await (const chunk of stream) {
+          chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+      } catch {
+        return null;
+      }
+    },
+    putObject: async (key: string, data: Buffer): Promise<void> => {
+      await bucket.fastPut({ path: key, contents: data, overwrite: true });
+    },
+    deleteObject: async (key: string): Promise<void> => {
+      await bucket.fastRemove({ path: key });
+    },
+    listObjects: async (prefix: string): Promise<string[]> => {
+      const files = await bucket.fastList({ prefix });
+      return files.map(f => f.name);
+    },
+  };
+
+  const cleanup = async () => {
+    try {
+      const files = await bucket.fastList({});
+      for (const file of files) {
+        await bucket.fastRemove({ path: file.name });
+      }
+      await s3.removeBucket(bucketName);
+    } catch {
+      // Ignore cleanup errors
+    }
+  };
+
+  return { storage, bucket, cleanup };
+}

test/test.auth.provider.ts

@@ -0,0 +1,412 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { DefaultAuthProvider } from '../ts/core/classes.defaultauthprovider.js';
+import { AuthManager } from '../ts/core/classes.authmanager.js';
+import type { IAuthProvider } from '../ts/core/interfaces.auth.js';
+import type { IAuthConfig, IAuthToken } from '../ts/core/interfaces.core.js';
+import { createMockAuthProvider } from './helpers/registry.js';
+
+// ============================================================================
+// Test State
+// ============================================================================
+
+let provider: DefaultAuthProvider;
+let authConfig: IAuthConfig;
+
+// ============================================================================
+// Setup
+// ============================================================================
+
+tap.test('setup: should create DefaultAuthProvider', async () => {
+  authConfig = {
+    jwtSecret: 'test-secret-key-for-jwt-signing',
+    tokenStore: 'memory',
+    npmTokens: { enabled: true },
+    ociTokens: {
+      enabled: true,
+      realm: 'https://auth.example.com/token',
+      service: 'test-registry',
+    },
+    mavenTokens: { enabled: true },
+    cargoTokens: { enabled: true },
+    composerTokens: { enabled: true },
+    pypiTokens: { enabled: true },
+    rubygemsTokens: { enabled: true },
+  };
+
+  provider = new DefaultAuthProvider(authConfig);
+  await provider.init();
+  expect(provider).toBeInstanceOf(DefaultAuthProvider);
+});
+
+// ============================================================================
+// Authentication Tests
+// ============================================================================
+
+tap.test('authenticate: should authenticate new user (auto-registration)', async () => {
+  const userId = await provider.authenticate({
+    username: 'newuser',
+    password: 'newpassword',
+  });
+
+  expect(userId).toEqual('newuser');
+});
+
+tap.test('authenticate: should authenticate existing user with correct password', async () => {
+  // First registration
+  await provider.authenticate({
+    username: 'existinguser',
+    password: 'correctpass',
+  });
+
+  // Second authentication with same credentials
+  const userId = await provider.authenticate({
+    username: 'existinguser',
+    password: 'correctpass',
+  });
+
+  expect(userId).toEqual('existinguser');
+});
+
+tap.test('authenticate: should reject authentication with wrong password', async () => {
+  // First registration
+  await provider.authenticate({
+    username: 'passworduser',
+    password: 'originalpass',
+  });
+
+  // Attempt with wrong password
+  const userId = await provider.authenticate({
+    username: 'passworduser',
+    password: 'wrongpass',
+  });
+
+  expect(userId).toBeNull();
+});
+
+// ============================================================================
+// Token Creation Tests
+// ============================================================================
+
+tap.test('createToken: should create NPM token with correct scopes', async () => {
+  const token = await provider.createToken('testuser', 'npm', {
+    scopes: ['npm:package:*:*'],
+  });
+
+  expect(token).toBeTruthy();
+  expect(typeof token).toEqual('string');
+
+  // Validate the token
+  const validated = await provider.validateToken(token, 'npm');
+  expect(validated).toBeTruthy();
+  expect(validated!.type).toEqual('npm');
+  expect(validated!.userId).toEqual('testuser');
+  expect(validated!.scopes).toContain('npm:package:*:*');
+});
+
+tap.test('createToken: should create Maven token', async () => {
+  const token = await provider.createToken('mavenuser', 'maven', {
+    readonly: true,
+  });
+
+  expect(token).toBeTruthy();
+
+  const validated = await provider.validateToken(token, 'maven');
+  expect(validated).toBeTruthy();
+  expect(validated!.type).toEqual('maven');
+  expect(validated!.readonly).toBeTrue();
+});
+
+tap.test('createToken: should create OCI JWT token with correct claims', async () => {
+  const token = await provider.createToken('ociuser', 'oci', {
+    scopes: ['oci:repository:myrepo:push', 'oci:repository:myrepo:pull'],
+    expiresIn: 3600,
+  });
+
+  expect(token).toBeTruthy();
+  // OCI tokens are JWTs (contain dots)
+  expect(token.split('.').length).toEqual(3);
+
+  const validated = await provider.validateToken(token, 'oci');
+  expect(validated).toBeTruthy();
+  expect(validated!.type).toEqual('oci');
+  expect(validated!.userId).toEqual('ociuser');
+  expect(validated!.scopes.length).toBeGreaterThan(0);
+});
+
+tap.test('createToken: should create token with expiration', async () => {
+  const token = await provider.createToken('expiryuser', 'npm', {
+    expiresIn: 60, // 60 seconds
+  });
+
+  const validated = await provider.validateToken(token, 'npm');
+  expect(validated).toBeTruthy();
+  expect(validated!.expiresAt).toBeTruthy();
+  expect(validated!.expiresAt!.getTime()).toBeGreaterThan(Date.now());
+});
+
+// ============================================================================
+// Token Validation Tests
+// ============================================================================
+
+tap.test('validateToken: should validate UUID token (NPM, Maven, etc.)', async () => {
+  const npmToken = await provider.createToken('validateuser', 'npm');
+  const validated = await provider.validateToken(npmToken);
+
+  expect(validated).toBeTruthy();
+  expect(validated!.type).toEqual('npm');
+  expect(validated!.userId).toEqual('validateuser');
+});
+
+tap.test('validateToken: should validate OCI JWT token', async () => {
+  const ociToken = await provider.createToken('ocivalidate', 'oci', {
+    scopes: ['oci:repository:*:*'],
+  });
+
+  const validated = await provider.validateToken(ociToken, 'oci');
+
+  expect(validated).toBeTruthy();
+  expect(validated!.type).toEqual('oci');
+  expect(validated!.userId).toEqual('ocivalidate');
+});
+
+tap.test('validateToken: should reject expired tokens', async () => {
+  const token = await provider.createToken('expireduser', 'npm', {
+    expiresIn: -1, // Already expired (in the past)
+  });
+
+  // The token should be created but will fail validation due to expiry
+  const validated = await provider.validateToken(token, 'npm');
+
+  // Token should be rejected because it's expired
+  expect(validated).toBeNull();
+});
+
+tap.test('validateToken: should reject invalid token', async () => {
+  const validated = await provider.validateToken('invalid-random-token');
+  expect(validated).toBeNull();
+});
+
+tap.test('validateToken: should reject token with wrong protocol', async () => {
+  const npmToken = await provider.createToken('protocoluser', 'npm');
+
+  // Try to validate as Maven token
+  const validated = await provider.validateToken(npmToken, 'maven');
+  expect(validated).toBeNull();
+});
+
+// ============================================================================
+// Token Revocation Tests
+// ============================================================================
+
+tap.test('revokeToken: should revoke tokens', async () => {
+  const token = await provider.createToken('revokeuser', 'npm');
+
+  // Verify token works before revocation
+  let validated = await provider.validateToken(token);
+  expect(validated).toBeTruthy();
+
+  // Revoke the token
+  await provider.revokeToken(token);
+
+  // Token should no longer be valid
+  validated = await provider.validateToken(token);
+  expect(validated).toBeNull();
+});
+
+// ============================================================================
+// Authorization Tests
+// ============================================================================
+
+tap.test('authorize: should authorize read actions for readonly tokens', async () => {
+  const token = await provider.createToken('readonlyuser', 'npm', {
+    readonly: true,
+    scopes: ['npm:package:*:read'],
+  });
+
+  const validated = await provider.validateToken(token);
+
+  const canRead = await provider.authorize(validated, 'npm:package:lodash', 'read');
+  expect(canRead).toBeTrue();
+
+  const canPull = await provider.authorize(validated, 'npm:package:lodash', 'pull');
+  expect(canPull).toBeTrue();
+});
+
+tap.test('authorize: should deny write actions for readonly tokens', async () => {
+  const token = await provider.createToken('readonlyuser2', 'npm', {
+    readonly: true,
+    scopes: ['npm:package:*:*'],
+  });
+
+  const validated = await provider.validateToken(token);
+
+  const canWrite = await provider.authorize(validated, 'npm:package:lodash', 'write');
+  expect(canWrite).toBeFalse();
+
+  const canPush = await provider.authorize(validated, 'npm:package:lodash', 'push');
+  expect(canPush).toBeFalse();
+
+  const canDelete = await provider.authorize(validated, 'npm:package:lodash', 'delete');
+  expect(canDelete).toBeFalse();
+});
+
+tap.test('authorize: should match scopes with wildcards', async () => {
+  // The scope system uses literal * as wildcard, not glob patterns
+  // npm:*:*:* means "all types, all names, all actions under npm"
+  const token = await provider.createToken('wildcarduser', 'npm', {
+    scopes: ['npm:*:*:*'],
+  });
+
+  const validated = await provider.validateToken(token);
+
+  // Should match any npm resource with full wildcard scope
+  const canAccessAnyPackage = await provider.authorize(validated, 'npm:package:lodash', 'read');
+  expect(canAccessAnyPackage).toBeTrue();
+
+  const canAccessScopedPackage = await provider.authorize(validated, 'npm:package:@myorg/foo', 'write');
+  expect(canAccessScopedPackage).toBeTrue();
+});
+
+tap.test('authorize: should deny access with null token', async () => {
+  const canAccess = await provider.authorize(null, 'npm:package:lodash', 'read');
+  expect(canAccess).toBeFalse();
+});
+
+// ============================================================================
+// List Tokens Tests
+// ============================================================================
+
+tap.test('listUserTokens: should list user tokens', async () => {
+  // Create multiple tokens for the same user
+  const userId = 'listtokenuser';
+  await provider.createToken(userId, 'npm');
+  await provider.createToken(userId, 'maven', { readonly: true });
+  await provider.createToken(userId, 'cargo');
+
+  const tokens = await provider.listUserTokens!(userId);
+
+  expect(tokens.length).toBeGreaterThanOrEqual(3);
+
+  // Check that tokens have expected properties
+  for (const token of tokens) {
+    expect(token.key).toBeTruthy();
+    expect(typeof token.readonly).toEqual('boolean');
+    expect(token.created).toBeTruthy();
+  }
+
+  // Verify we have different protocols
+  const protocols = tokens.map(t => t.protocol);
+  expect(protocols).toContain('npm');
+  expect(protocols).toContain('maven');
+  expect(protocols).toContain('cargo');
+});
+
+// ============================================================================
+// AuthManager Integration Tests
+// ============================================================================
+
+tap.test('AuthManager: should accept custom IAuthProvider', async () => {
+  const mockProvider = createMockAuthProvider({
+    authenticate: async (credentials) => {
+      if (credentials.username === 'custom' && credentials.password === 'pass') {
+        return 'custom-user-id';
+      }
+      return null;
+    },
+  });
+
+  const manager = new AuthManager(authConfig, mockProvider);
+  await manager.init();
+
+  // Use the custom provider
+  const userId = await manager.authenticate({
+    username: 'custom',
+    password: 'pass',
+  });
+
+  expect(userId).toEqual('custom-user-id');
+
+  // Wrong credentials should fail
+  const failed = await manager.authenticate({
+    username: 'custom',
+    password: 'wrong',
+  });
+
+  expect(failed).toBeNull();
+});
+
+tap.test('AuthManager: should use default provider when none specified', async () => {
+  const manager = new AuthManager(authConfig);
+  await manager.init();
+
+  // Should use DefaultAuthProvider internally
+  const userId = await manager.authenticate({
+    username: 'defaultuser',
+    password: 'defaultpass',
+  });
+
+  expect(userId).toEqual('defaultuser');
+});
+
+tap.test('AuthManager: should delegate token creation to provider', async () => {
+  let tokenCreated = false;
+  const mockProvider = createMockAuthProvider({
+    createToken: async (userId, protocol, options) => {
+      tokenCreated = true;
+      return `mock-token-${protocol}-${userId}`;
+    },
+  });
+
+  const manager = new AuthManager(authConfig, mockProvider);
+  await manager.init();
+
+  const token = await manager.createNpmToken('delegateuser', false);
+
+  expect(tokenCreated).toBeTrue();
+  expect(token).toContain('mock-token-npm');
+});
+
+// ============================================================================
+// Edge Cases
+// ============================================================================
+
+tap.test('edge: should handle concurrent token operations', async () => {
+  const promises: Promise<string>[] = [];
+
+  // Create 10 tokens concurrently
+  for (let i = 0; i < 10; i++) {
+    promises.push(provider.createToken(`concurrent-user-${i}`, 'npm'));
+  }
+
+  const tokens = await Promise.all(promises);
+
+  // All tokens should be unique
+  const uniqueTokens = new Set(tokens);
+  expect(uniqueTokens.size).toEqual(10);
+
+  // All tokens should be valid
+  for (const token of tokens) {
+    const validated = await provider.validateToken(token);
+    expect(validated).toBeTruthy();
+  }
+});
+
+tap.test('edge: should handle empty scopes', async () => {
+  const token = await provider.createToken('emptyuser', 'npm', {
+    scopes: [],
+  });
+
+  const validated = await provider.validateToken(token);
+  expect(validated).toBeTruthy();
+  // Even with empty scopes, token should be valid
+});
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+tap.test('cleanup', async () => {
+  // No cleanup needed for in-memory provider
+});
+
+export default tap.start();

test/test.cargo.nativecli.node.ts

@@ -79,16 +79,10 @@ async function createHttpServer(
           res.setHeader(key, value);
         }
 
-        // Send body
+        // Send body (response.body is always ReadableStream<Uint8Array> or undefined)
         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));
-          }
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
         } else {
           res.end();
         }
@@ -251,8 +245,11 @@ function cleanupTestDir(dir: string): void {
 // ========================================================================
 
 tap.test('Cargo CLI: should setup registry and HTTP server', async () => {
-  // Create registry
-  registry = await createTestRegistry();
+  // Use port 5000
+  registryPort = 5000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
   const tokens = await createTestTokens(registry);
   cargoToken = tokens.cargoToken;
 
@@ -266,10 +263,6 @@ tap.test('Cargo CLI: should setup registry and HTTP server', async () => {
   } catch (error) {
     // Ignore error if operation fails
   }
-
-  // Use port 5000 (hardcoded in CargoRegistry default config)
-  // TODO: Once registryUrl is configurable, use dynamic port like npm test (35001)
-  registryPort = 5000;
   const serverSetup = await createHttpServer(registry, registryPort);
   server = serverSetup.server;
   registryUrl = serverSetup.url;

test/test.composer.nativecli.node.ts

@@ -0,0 +1,462 @@
+/**
+ * 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, generateTestRunId } 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;
+let hasComposer = false;
+
+// Unique test run ID to avoid conflicts between test runs
+const testRunId = generateTestRunId();
+const testPackageName = `testvendor/test-pkg-${testRunId}`;
+
+/**
+ * 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 (response.body is always ReadableStream<Uint8Array> or undefined)
+        if (response.body) {
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
+        } 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));
+    hasComposer = result.exitCode === 0;
+    expect(result.exitCode).toEqual(0);
+  } catch (error) {
+    console.log('Composer CLI not available, skipping native CLI tests');
+    hasComposer = false;
+  }
+});
+
+tap.test('Composer CLI: should setup registry and HTTP server', async () => {
+  // Use port 38000 (avoids conflicts with other tests)
+  registryPort = 38000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
+  const tokens = await createTestTokens(registry);
+  composerToken = tokens.composerToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(composerToken).toBeTypeOf('string');
+  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 version = '1.0.0';
+
+  await uploadComposerPackage(testPackageName, version, composerToken, registryUrl);
+
+  // Verify package exists via p2 metadata endpoint (more reliable than packages.json for new packages)
+  const metadataResponse = await fetch(`${registryUrl}/composer/p2/${testPackageName}.json`);
+  expect(metadataResponse.status).toEqual(200);
+
+  const metadata = await metadataResponse.json();
+  expect(metadata.packages).toBeDefined();
+  expect(metadata.packages[testPackageName]).toBeDefined();
+  expect(metadata.packages[testPackageName].length).toBeGreaterThan(0);
+});
+
+tap.test('Composer CLI: should require package from registry', async () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  const projectDir = path.join(testDir, 'consumer-project');
+  createComposerProject(projectDir, registryUrl);
+
+  // Try to require the package we uploaded
+  const result = await runComposerCommand(
+    `require ${testPackageName}: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 () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  const projectDir = path.join(testDir, 'consumer-project');
+  // Parse vendor/package from testPackageName (e.g., "testvendor/test-pkg-abc123")
+  const [vendor, pkg] = testPackageName.split('/');
+  const packageDir = path.join(projectDir, 'vendor', vendor, pkg);
+
+  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 version = '2.0.0';
+
+  await uploadComposerPackage(testPackageName, version, composerToken, registryUrl);
+
+  // Verify both versions exist via p2 metadata endpoint (Composer v2 format)
+  const response = await fetch(`${registryUrl}/composer/p2/${testPackageName}.json`);
+  expect(response.status).toEqual(200);
+
+  const metadata = await response.json();
+  expect(metadata.packages).toBeDefined();
+  expect(metadata.packages[testPackageName]).toBeDefined();
+  // Check that both versions are present
+  const versions = metadata.packages[testPackageName];
+  expect(versions.length).toBeGreaterThanOrEqual(2);
+  const versionNumbers = versions.map((v: any) => v.version);
+  expect(versionNumbers).toContain('1.0.0');
+  expect(versionNumbers).toContain('2.0.0');
+});
+
+tap.test('Composer CLI: should update to new version', async () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  // Update to version 2.0.0
+  const result = await runComposerCommand(
+    `require ${testPackageName}: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 === testPackageName);
+  expect(pkg?.version).toEqual('2.0.0');
+});
+
+tap.test('Composer CLI: should search for packages', async () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  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 () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  const result = await runComposerCommand(
+    `show ${testPackageName} --no-interaction`,
+    projectDir
+  );
+  console.log('composer show output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+  expect(result.stdout).toContain(testPackageName);
+});
+
+tap.test('Composer CLI: should remove package', async () => {
+  if (!hasComposer) {
+    console.log('Skipping - composer not available');
+    return;
+  }
+
+  const projectDir = path.join(testDir, 'consumer-project');
+
+  const result = await runComposerCommand(
+    `remove ${testPackageName} --no-interaction`,
+    projectDir
+  );
+  console.log('composer remove output:', result.stdout);
+
+  expect(result.exitCode).toEqual(0);
+
+  // Verify package is removed from vendor
+  const [vendor, pkg] = testPackageName.split('/');
+  const packageDir = path.join(projectDir, 'vendor', vendor, pkg);
+  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.composer.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import { createTestRegistry, createTestTokens, createComposerZip } from './helpers/registry.js';
 
 let registry: SmartRegistry;
@@ -41,9 +42,10 @@ tap.test('Composer: should return packages.json (GET /packages.json)', async ()
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('metadata-url');
-  expect(response.body).toHaveProperty('available-packages');
-  expect(response.body['available-packages']).toBeInstanceOf(Array);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('metadata-url');
+  expect(body).toHaveProperty('available-packages');
+  expect(body['available-packages']).toBeInstanceOf(Array);
 });
 
 tap.test('Composer: should upload a package (PUT /packages/{vendor/package})', async () => {
@@ -59,9 +61,10 @@ tap.test('Composer: should upload a package (PUT /packages/{vendor/package})', a
   });
 
   expect(response.status).toEqual(201);
-  expect(response.body.status).toEqual('success');
-  expect(response.body.package).toEqual(testPackageName);
-  expect(response.body.version).toEqual(testVersion);
+  const body = await streamToJson(response.body);
+  expect(body.status).toEqual('success');
+  expect(body.package).toEqual(testPackageName);
+  expect(body.version).toEqual(testVersion);
 });
 
 tap.test('Composer: should retrieve package metadata (GET /p2/{vendor/package}.json)', async () => {
@@ -73,11 +76,12 @@ tap.test('Composer: should retrieve package metadata (GET /p2/{vendor/package}.j
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('packages');
-  expect(response.body.packages[testPackageName]).toBeInstanceOf(Array);
-  expect(response.body.packages[testPackageName].length).toEqual(1);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('packages');
+  expect(body.packages[testPackageName]).toBeInstanceOf(Array);
+  expect(body.packages[testPackageName].length).toEqual(1);
 
-  const packageData = response.body.packages[testPackageName][0];
+  const packageData = body.packages[testPackageName][0];
   expect(packageData.name).toEqual(testPackageName);
   expect(packageData.version).toEqual(testVersion);
   expect(packageData.version_normalized).toEqual('1.0.0.0');
@@ -97,7 +101,8 @@ tap.test('Composer: should download package ZIP (GET /dists/{vendor/package}/{re
     query: {},
   });
 
-  const reference = metadataResponse.body.packages[testPackageName][0].dist.reference;
+  const metaBody = await streamToJson(metadataResponse.body);
+  const reference = metaBody.packages[testPackageName][0].dist.reference;
 
   const response = await registry.handleRequest({
     method: 'GET',
@@ -107,7 +112,8 @@ tap.test('Composer: should download package ZIP (GET /dists/{vendor/package}/{re
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
   expect(response.headers['Content-Type']).toEqual('application/zip');
   expect(response.headers['Content-Disposition']).toContain('attachment');
 });
@@ -121,9 +127,10 @@ tap.test('Composer: should list packages (GET /packages/list.json)', async () =>
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('packageNames');
-  expect(response.body.packageNames).toBeInstanceOf(Array);
-  expect(response.body.packageNames).toContain(testPackageName);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('packageNames');
+  expect(body.packageNames).toBeInstanceOf(Array);
+  expect(body.packageNames).toContain(testPackageName);
 });
 
 tap.test('Composer: should filter package list (GET /packages/list.json?filter=vendor/*)', async () => {
@@ -135,8 +142,9 @@ tap.test('Composer: should filter package list (GET /packages/list.json?filter=v
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body.packageNames).toBeInstanceOf(Array);
-  expect(response.body.packageNames).toContain(testPackageName);
+  const body = await streamToJson(response.body);
+  expect(body.packageNames).toBeInstanceOf(Array);
+  expect(body.packageNames).toContain(testPackageName);
 });
 
 tap.test('Composer: should prevent duplicate version upload', async () => {
@@ -152,8 +160,9 @@ tap.test('Composer: should prevent duplicate version upload', async () => {
   });
 
   expect(response.status).toEqual(409);
-  expect(response.body.status).toEqual('error');
-  expect(response.body.message).toContain('already exists');
+  const body = await streamToJson(response.body);
+  expect(body.status).toEqual('error');
+  expect(body.message).toContain('already exists');
 });
 
 tap.test('Composer: should upload a second version', async () => {
@@ -172,8 +181,9 @@ tap.test('Composer: should upload a second version', async () => {
   });
 
   expect(response.status).toEqual(201);
-  expect(response.body.status).toEqual('success');
-  expect(response.body.version).toEqual(testVersion2);
+  const body = await streamToJson(response.body);
+  expect(body.status).toEqual('success');
+  expect(body.version).toEqual(testVersion2);
 });
 
 tap.test('Composer: should return multiple versions in metadata', async () => {
@@ -185,10 +195,11 @@ tap.test('Composer: should return multiple versions in metadata', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body.packages[testPackageName]).toBeInstanceOf(Array);
-  expect(response.body.packages[testPackageName].length).toEqual(2);
+  const body = await streamToJson(response.body);
+  expect(body.packages[testPackageName]).toBeInstanceOf(Array);
+  expect(body.packages[testPackageName].length).toEqual(2);
 
-  const versions = response.body.packages[testPackageName].map((p: any) => p.version);
+  const versions = body.packages[testPackageName].map((p: any) => p.version);
   expect(versions).toContain('1.0.0');
   expect(versions).toContain('1.1.0');
 });
@@ -213,8 +224,9 @@ tap.test('Composer: should delete a specific version (DELETE /packages/{vendor/p
     query: {},
   });
 
-  expect(metadataResponse.body.packages[testPackageName].length).toEqual(1);
-  expect(metadataResponse.body.packages[testPackageName][0].version).toEqual('1.1.0');
+  const metaBody = await streamToJson(metadataResponse.body);
+  expect(metaBody.packages[testPackageName].length).toEqual(1);
+  expect(metaBody.packages[testPackageName][0].version).toEqual('1.1.0');
 });
 
 tap.test('Composer: should require auth for package upload', async () => {
@@ -231,7 +243,8 @@ tap.test('Composer: should require auth for package upload', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body.status).toEqual('error');
+  const body = await streamToJson(response.body);
+  expect(body.status).toEqual('error');
 });
 
 tap.test('Composer: should reject invalid ZIP (no composer.json)', async () => {
@@ -249,8 +262,9 @@ tap.test('Composer: should reject invalid ZIP (no composer.json)', async () => {
   });
 
   expect(response.status).toEqual(400);
-  expect(response.body.status).toEqual('error');
-  expect(response.body.message).toContain('composer.json');
+  const body = await streamToJson(response.body);
+  expect(body.status).toEqual('error');
+  expect(body.message).toContain('composer.json');
 });
 
 tap.test('Composer: should delete entire package (DELETE /packages/{vendor/package})', async () => {

test/test.integration.crossprotocol.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import {
   createTestRegistry,
   createTestTokens,
@@ -79,7 +80,9 @@ tap.test('Integration: should handle /simple path for PyPI', async () => {
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toStartWith('text/html');
-  expect(response.body).toContain('integration-test-py');
+  const body = await streamToBuffer(response.body);
+  const text = body.toString('utf-8');
+  expect(text).toContain('integration-test-py');
 });
 
 tap.test('Integration: should reject PyPI token for RubyGems endpoint', async () => {
@@ -135,8 +138,9 @@ tap.test('Integration: should return 404 for unknown paths', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
-  expect((response.body as any).error).toEqual('NOT_FOUND');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
+  expect(body.error).toEqual('NOT_FOUND');
 });
 
 tap.test('Integration: should retrieve PyPI registry instance', async () => {

test/test.integration.smarts3.node.ts

@@ -1,32 +1,34 @@
 /**
- * Integration test for smartregistry with smarts3
+ * Integration test for smartregistry with smartstorage
  * Verifies that smartregistry works with a local S3-compatible server
  */
 
 import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as smarts3Module from '@push.rocks/smarts3';
+import * as smartstorageModule from '@push.rocks/smartstorage';
 import { SmartRegistry } from '../ts/classes.smartregistry.js';
 import type { IRegistryConfig } from '../ts/core/interfaces.core.js';
+import { streamToJson } from '../ts/core/helpers.stream.js';
 import * as crypto from 'crypto';
 
-let s3Server: smarts3Module.Smarts3;
+let s3Server: smartstorageModule.SmartStorage;
 let registry: SmartRegistry;
 
 /**
- * Setup: Start smarts3 server
+ * Setup: Start smartstorage server
  */
-tap.test('should start smarts3 server', async () => {
-  s3Server = await smarts3Module.Smarts3.createAndStart({
+tap.test('should start smartstorage server', async () => {
+  s3Server = await smartstorageModule.SmartStorage.createAndStart({
     server: {
-      port: 3456, // Use different port to avoid conflicts with other tests
-      host: '0.0.0.0',
+      port: 3456,
+      address: '0.0.0.0',
+      silent: true,
     },
     storage: {
-      cleanSlate: true, // Fresh storage for each test run
-      bucketsDir: './.nogit/smarts3-test-buckets',
+      cleanSlate: true,
+      directory: './.nogit/smartstorage-test-buckets',
     },
     logging: {
-      silent: true, // Reduce test output noise
+      enabled: false,
     },
   });
 
@@ -34,20 +36,10 @@ tap.test('should start smarts3 server', async () => {
 });
 
 /**
- * Setup: Create SmartRegistry with smarts3 configuration
+ * Setup: Create SmartRegistry with smartstorage configuration
  */
 tap.test('should create SmartRegistry instance with smarts3 IS3Descriptor', async () => {
-  // Manually construct IS3Descriptor based on smarts3 configuration
-  // Note: smarts3.getS3Descriptor() returns empty object as of v5.1.0
-  // This is a known limitation - smarts3 doesn't expose its config properly
-  const s3Descriptor = {
-    endpoint: 'localhost',
-    port: 3456,
-    accessKey: 'test',  // smarts3 doesn't require real credentials
-    accessSecret: 'test',
-    useSsl: false,
-    region: 'us-east-1',
-  };
+  const s3Descriptor = await s3Server.getStorageDescriptor();
 
   const config: IRegistryConfig = {
     storage: {
@@ -97,7 +89,7 @@ tap.test('should create SmartRegistry instance with smarts3 IS3Descriptor', asyn
 });
 
 /**
- * Test NPM protocol with smarts3
+ * Test NPM protocol with smartstorage
  */
 tap.test('NPM: should publish package to smarts3', async () => {
   const authManager = registry.getAuthManager();
@@ -139,7 +131,7 @@ tap.test('NPM: should publish package to smarts3', async () => {
     body: packageData,
   });
 
-  expect(response.status).toEqual(201); // 201 Created is correct for publishing
+  expect(response.status).toEqual(201);
 });
 
 tap.test('NPM: should retrieve package from smarts3', async () => {
@@ -151,12 +143,13 @@ tap.test('NPM: should retrieve package from smarts3', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('name');
-  expect(response.body.name).toEqual('test-package-smarts3');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('name');
+  expect(body.name).toEqual('test-package-smarts3');
 });
 
 /**
- * Test OCI protocol with smarts3
+ * Test OCI protocol with smartstorage
  */
 tap.test('OCI: should store blob in smarts3', async () => {
   const authManager = registry.getAuthManager();
@@ -173,7 +166,7 @@ tap.test('OCI: should store blob in smarts3', async () => {
   // Initiate blob upload
   const initiateResponse = await registry.handleRequest({
     method: 'POST',
-    path: '/oci/v2/test-image/blobs/uploads/',
+    path: '/oci/test-image/blobs/uploads/',
     headers: {
       'Authorization': `Bearer ${token}`,
     },
@@ -196,7 +189,7 @@ tap.test('OCI: should store blob in smarts3', async () => {
 
   const uploadResponse = await registry.handleRequest({
     method: 'PUT',
-    path: `/oci/v2/test-image/blobs/uploads/${uploadId}`,
+    path: `/oci/test-image/blobs/uploads/${uploadId}`,
     headers: {
       'Authorization': `Bearer ${token}`,
       'Content-Type': 'application/octet-stream',
@@ -209,18 +202,9 @@ tap.test('OCI: should store blob in smarts3', async () => {
 });
 
 /**
- * Test PyPI protocol with smarts3
+ * Test PyPI protocol with smartstorage
  */
 tap.test('PyPI: should upload package to smarts3', async () => {
-  const authManager = registry.getAuthManager();
-  const userId = await authManager.authenticate({
-    username: 'testuser',
-    password: 'testpass',
-  });
-  const token = await authManager.createPypiToken(userId, false);
-
-  // Note: In a real test, this would be multipart/form-data
-  // For simplicity, we're testing the storage layer
   const storage = registry.getStorage();
 
   // Store a test package file
@@ -252,7 +236,7 @@ tap.test('PyPI: should upload package to smarts3', async () => {
 });
 
 /**
- * Test Cargo protocol with smarts3
+ * Test Cargo protocol with smartstorage
  */
 tap.test('Cargo: should store crate in smarts3', async () => {
   const storage = registry.getStorage();
@@ -281,11 +265,11 @@ tap.test('Cargo: should store crate in smarts3', async () => {
 });
 
 /**
- * Cleanup: Stop smarts3 server
+ * Cleanup: Stop smartstorage server
  */
-tap.test('should stop smarts3 server', async () => {
+tap.test('should stop smartstorage server', async () => {
   await s3Server.stop();
-  expect(true).toEqual(true); // Just verify it completes without error
+  expect(true).toEqual(true);
 });
 
 export default tap.start();

test/test.maven.nativecli.node.ts

@@ -0,0 +1,484 @@
+/**
+ * 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 (response.body is always ReadableStream<Uint8Array> or undefined)
+        if (response.body) {
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
+        } 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 () => {
+  // Use port 37000 (avoids conflicts with other tests)
+  registryPort = 37000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
+  const tokens = await createTestTokens(registry);
+  mavenToken = tokens.mavenToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(mavenToken).toBeTypeOf('string');
+  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.maven.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import {
   createTestRegistry,
   createTestTokens,
@@ -88,10 +89,11 @@ tap.test('Maven: should retrieve uploaded POM file (GET)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toContain(testGroupId);
-  expect((response.body as Buffer).toString('utf-8')).toContain(testArtifactId);
-  expect((response.body as Buffer).toString('utf-8')).toContain(testVersion);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toContain(testGroupId);
+  expect(body.toString('utf-8')).toContain(testArtifactId);
+  expect(body.toString('utf-8')).toContain(testVersion);
   expect(response.headers['Content-Type']).toEqual('application/xml');
 });
 
@@ -107,7 +109,8 @@ tap.test('Maven: should retrieve uploaded JAR file (GET)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
   expect(response.headers['Content-Type']).toEqual('application/java-archive');
 });
 
@@ -124,8 +127,9 @@ tap.test('Maven: should retrieve MD5 checksum for JAR (GET *.jar.md5)', async ()
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual(checksums.md5);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual(checksums.md5);
   expect(response.headers['Content-Type']).toEqual('text/plain');
 });
 
@@ -142,8 +146,9 @@ tap.test('Maven: should retrieve SHA1 checksum for JAR (GET *.jar.sha1)', async
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual(checksums.sha1);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual(checksums.sha1);
   expect(response.headers['Content-Type']).toEqual('text/plain');
 });
 
@@ -160,8 +165,9 @@ tap.test('Maven: should retrieve SHA256 checksum for JAR (GET *.jar.sha256)', as
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual(checksums.sha256);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual(checksums.sha256);
   expect(response.headers['Content-Type']).toEqual('text/plain');
 });
 
@@ -178,8 +184,9 @@ tap.test('Maven: should retrieve SHA512 checksum for JAR (GET *.jar.sha512)', as
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual(checksums.sha512);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual(checksums.sha512);
   expect(response.headers['Content-Type']).toEqual('text/plain');
 });
 
@@ -194,8 +201,9 @@ tap.test('Maven: should retrieve maven-metadata.xml (GET)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  const xml = (response.body as Buffer).toString('utf-8');
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  const xml = body.toString('utf-8');
   expect(xml).toContain('<groupId>');
   expect(xml).toContain('<artifactId>');
   expect(xml).toContain('<version>1.0.0</version>');
@@ -247,7 +255,8 @@ tap.test('Maven: should upload a second version and update metadata', async () =
   });
 
   expect(response.status).toEqual(200);
-  const xml = (response.body as Buffer).toString('utf-8');
+  const metaBody = await streamToBuffer(response.body);
+  const xml = metaBody.toString('utf-8');
   expect(xml).toContain('<version>1.0.0</version>');
   expect(xml).toContain('<version>2.0.0</version>');
   expect(xml).toContain('<latest>2.0.0</latest>');
@@ -285,7 +294,8 @@ tap.test('Maven: should return 404 for non-existent artifact', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('Maven: should return 401 for unauthorized upload', async () => {
@@ -304,7 +314,8 @@ tap.test('Maven: should return 401 for unauthorized upload', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('Maven: should reject POM upload with mismatched GAV', async () => {
@@ -328,7 +339,8 @@ tap.test('Maven: should reject POM upload with mismatched GAV', async () => {
   });
 
   expect(response.status).toEqual(400);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('Maven: should delete an artifact (DELETE)', async () => {

test/test.npm.nativecli.node.ts

@@ -79,16 +79,10 @@ async function createHttpServer(
           res.setHeader(key, value);
         }
 
-        // Send body
+        // Send body (response.body is always ReadableStream<Uint8Array> or undefined)
         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));
-          }
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
         } else {
           res.end();
         }
@@ -224,16 +218,16 @@ function cleanupTestDir(dir: string): void {
 // ========================================================================
 
 tap.test('NPM CLI: should setup registry and HTTP server', async () => {
-  // Create registry
-  registry = await createTestRegistry();
+  // Find available port
+  registryPort = 35000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
   const tokens = await createTestTokens(registry);
   npmToken = tokens.npmToken;
 
   expect(registry).toBeInstanceOf(SmartRegistry);
   expect(npmToken).toBeTypeOf('string');
-
-  // Find available port
-  registryPort = 35000;
   const serverSetup = await createHttpServer(registry, registryPort);
   server = serverSetup.server;
   registryUrl = serverSetup.url;

test/test.npm.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import { createTestRegistry, createTestTokens, createTestPackument } from './helpers/registry.js';
 
 let registry: SmartRegistry;
@@ -34,8 +35,9 @@ tap.test('NPM: should handle user authentication (PUT /-/user/org.couchdb.user:{
   });
 
   expect(response.status).toEqual(201);
-  expect(response.body).toHaveProperty('token');
-  expect((response.body as any).token).toBeTypeOf('string');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('token');
+  expect(body.token).toBeTypeOf('string');
 });
 
 tap.test('NPM: should publish a package (PUT /{package})', async () => {
@@ -53,8 +55,9 @@ tap.test('NPM: should publish a package (PUT /{package})', async () => {
   });
 
   expect(response.status).toEqual(201);
-  expect(response.body).toHaveProperty('ok');
-  expect((response.body as any).ok).toEqual(true);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('ok');
+  expect(body.ok).toEqual(true);
 });
 
 tap.test('NPM: should retrieve package metadata (GET /{package})', async () => {
@@ -66,10 +69,11 @@ tap.test('NPM: should retrieve package metadata (GET /{package})', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('name');
-  expect((response.body as any).name).toEqual(testPackageName);
-  expect((response.body as any).versions).toHaveProperty(testVersion);
-  expect((response.body as any)['dist-tags'].latest).toEqual(testVersion);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('name');
+  expect(body.name).toEqual(testPackageName);
+  expect(body.versions).toHaveProperty(testVersion);
+  expect(body['dist-tags'].latest).toEqual(testVersion);
 });
 
 tap.test('NPM: should retrieve specific version metadata (GET /{package}/{version})', async () => {
@@ -81,9 +85,10 @@ tap.test('NPM: should retrieve specific version metadata (GET /{package}/{versio
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('version');
-  expect((response.body as any).version).toEqual(testVersion);
-  expect((response.body as any).name).toEqual(testPackageName);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('version');
+  expect(body.version).toEqual(testVersion);
+  expect(body.name).toEqual(testPackageName);
 });
 
 tap.test('NPM: should download tarball (GET /{package}/-/{tarball})', async () => {
@@ -95,8 +100,9 @@ tap.test('NPM: should download tarball (GET /{package}/-/{tarball})', async () =
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual('fake tarball content');
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual('fake tarball content');
   expect(response.headers['Content-Type']).toEqual('application/octet-stream');
 });
 
@@ -127,7 +133,8 @@ tap.test('NPM: should publish a new version of the package', async () => {
   });
 
   expect(getResponse.status).toEqual(200);
-  expect((getResponse.body as any).versions).toHaveProperty(newVersion);
+  const getBody = await streamToJson(getResponse.body);
+  expect(getBody.versions).toHaveProperty(newVersion);
 });
 
 tap.test('NPM: should get dist-tags (GET /-/package/{pkg}/dist-tags)', async () => {
@@ -139,8 +146,9 @@ tap.test('NPM: should get dist-tags (GET /-/package/{pkg}/dist-tags)', async ()
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('latest');
-  expect((response.body as any).latest).toBeTypeOf('string');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('latest');
+  expect(body.latest).toBeTypeOf('string');
 });
 
 tap.test('NPM: should update dist-tag (PUT /-/package/{pkg}/dist-tags/{tag})', async () => {
@@ -165,7 +173,8 @@ tap.test('NPM: should update dist-tag (PUT /-/package/{pkg}/dist-tags/{tag})', a
     query: {},
   });
 
-  expect((getResponse.body as any)['dist-tags'].beta).toEqual('1.1.0');
+  const getBody2 = await streamToJson(getResponse.body);
+  expect(getBody2['dist-tags'].beta).toEqual('1.1.0');
 });
 
 tap.test('NPM: should delete dist-tag (DELETE /-/package/{pkg}/dist-tags/{tag})', async () => {
@@ -188,7 +197,8 @@ tap.test('NPM: should delete dist-tag (DELETE /-/package/{pkg}/dist-tags/{tag})'
     query: {},
   });
 
-  expect((getResponse.body as any)['dist-tags']).not.toHaveProperty('beta');
+  const getBody3 = await streamToJson(getResponse.body);
+  expect(getBody3['dist-tags']).not.toHaveProperty('beta');
 });
 
 tap.test('NPM: should create a new token (POST /-/npm/v1/tokens)', async () => {
@@ -208,8 +218,9 @@ tap.test('NPM: should create a new token (POST /-/npm/v1/tokens)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('token');
-  expect((response.body as any).readonly).toEqual(true);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('token');
+  expect(body.readonly).toEqual(true);
 });
 
 tap.test('NPM: should list tokens (GET /-/npm/v1/tokens)', async () => {
@@ -223,9 +234,10 @@ tap.test('NPM: should list tokens (GET /-/npm/v1/tokens)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('objects');
-  expect((response.body as any).objects).toBeInstanceOf(Array);
-  expect((response.body as any).objects.length).toBeGreaterThan(0);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('objects');
+  expect(body.objects).toBeInstanceOf(Array);
+  expect(body.objects.length).toBeGreaterThan(0);
 });
 
 tap.test('NPM: should search packages (GET /-/v1/search)', async () => {
@@ -240,9 +252,10 @@ tap.test('NPM: should search packages (GET /-/v1/search)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('objects');
-  expect((response.body as any).objects).toBeInstanceOf(Array);
-  expect((response.body as any).total).toBeGreaterThan(0);
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('objects');
+  expect(body.objects).toBeInstanceOf(Array);
+  expect(body.total).toBeGreaterThan(0);
 });
 
 tap.test('NPM: should search packages with specific query', async () => {
@@ -256,7 +269,8 @@ tap.test('NPM: should search packages with specific query', async () => {
   });
 
   expect(response.status).toEqual(200);
-  const results = (response.body as any).objects;
+  const body = await streamToJson(response.body);
+  const results = body.objects;
   expect(results.length).toBeGreaterThan(0);
   expect(results[0].package.name).toEqual(testPackageName);
 });
@@ -281,7 +295,8 @@ tap.test('NPM: should unpublish a specific version (DELETE /{package}/-/{version
     query: {},
   });
 
-  expect((getResponse.body as any).versions).not.toHaveProperty(testVersion);
+  const getBody4 = await streamToJson(getResponse.body);
+  expect(getBody4.versions).not.toHaveProperty(testVersion);
 });
 
 tap.test('NPM: should unpublish entire package (DELETE /{package}/-rev/{rev})', async () => {
@@ -316,7 +331,8 @@ tap.test('NPM: should return 404 for non-existent package', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('NPM: should return 401 for unauthorized publish', async () => {
@@ -334,7 +350,8 @@ tap.test('NPM: should return 401 for unauthorized publish', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('NPM: should reject readonly token for write operations', async () => {

test/test.oci.nativecli.node.ts

@@ -48,7 +48,7 @@ async function createDockerTestRegistry(port: number): Promise<SmartRegistry> {
     },
     oci: {
       enabled: true,
-      basePath: '/oci',
+      basePath: '/v2',
     },
   };
 
@@ -95,8 +95,7 @@ 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
+ * SmartRegistry OCI is configured with basePath '/v2' matching Docker's native /v2/ prefix.
  *
  * Also implements a simple /v2/token endpoint for Docker Bearer auth flow
  */
@@ -130,10 +129,7 @@ async function createHttpServer(
         // 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;
-        }
+        // basePath is /v2 which matches Docker's native /v2/ prefix — no rewrite needed
 
         // Read raw body - ALWAYS preserve exact bytes for OCI
         const chunks: Buffer[] = [];
@@ -179,16 +175,10 @@ async function createHttpServer(
           res.setHeader(key, value);
         }
 
-        // Send body
+        // Send body (response.body is always ReadableStream<Uint8Array> or undefined)
         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));
-          }
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
         } else {
           res.end();
         }
@@ -313,7 +303,7 @@ 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/`);
+  const response = await fetch(`${registryUrl}/v2/`);
   expect(response.status).toEqual(200);
   console.log('OCI v2 response:', await response.json());
 });
@@ -352,7 +342,7 @@ tap.test('Docker CLI: should push image to registry', async () => {
 });
 
 tap.test('Docker CLI: should verify manifest in registry via API', async () => {
-  const response = await fetch(`${registryUrl}/oci/v2/test-image/tags/list`, {
+  const response = await fetch(`${registryUrl}/v2/test-image/tags/list`, {
     headers: { Authorization: `Bearer ${ociToken}` },
   });
 

test/test.oci.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import { createTestRegistry, createTestTokens, calculateDigest, createTestManifest } from './helpers/registry.js';
 
 let registry: SmartRegistry;
@@ -24,7 +25,7 @@ tap.test('OCI: should create registry instance', async () => {
 tap.test('OCI: should handle version check (GET /v2/)', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/',
+    path: '/oci/',
     headers: {},
     query: {},
   });
@@ -36,7 +37,7 @@ tap.test('OCI: should handle version check (GET /v2/)', async () => {
 tap.test('OCI: should initiate blob upload (POST /v2/{name}/blobs/uploads/)', async () => {
   const response = await registry.handleRequest({
     method: 'POST',
-    path: '/oci/v2/test-repo/blobs/uploads/',
+    path: '/oci/test-repo/blobs/uploads/',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -53,7 +54,7 @@ tap.test('OCI: should upload blob in single PUT', async () => {
 
   const response = await registry.handleRequest({
     method: 'POST',
-    path: '/oci/v2/test-repo/blobs/uploads/',
+    path: '/oci/test-repo/blobs/uploads/',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -73,7 +74,7 @@ tap.test('OCI: should upload config blob', async () => {
 
   const response = await registry.handleRequest({
     method: 'POST',
-    path: '/oci/v2/test-repo/blobs/uploads/',
+    path: '/oci/test-repo/blobs/uploads/',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -90,7 +91,7 @@ tap.test('OCI: should upload config blob', async () => {
 tap.test('OCI: should check if blob exists (HEAD /v2/{name}/blobs/{digest})', async () => {
   const response = await registry.handleRequest({
     method: 'HEAD',
-    path: `/oci/v2/test-repo/blobs/${testBlobDigest}`,
+    path: `/oci/test-repo/blobs/${testBlobDigest}`,
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -105,7 +106,7 @@ tap.test('OCI: should check if blob exists (HEAD /v2/{name}/blobs/{digest})', as
 tap.test('OCI: should retrieve blob (GET /v2/{name}/blobs/{digest})', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: `/oci/v2/test-repo/blobs/${testBlobDigest}`,
+    path: `/oci/test-repo/blobs/${testBlobDigest}`,
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -113,8 +114,9 @@ tap.test('OCI: should retrieve blob (GET /v2/{name}/blobs/{digest})', async () =
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).toString('utf-8')).toEqual('Hello from OCI test blob!');
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.toString('utf-8')).toEqual('Hello from OCI test blob!');
   expect(response.headers['Docker-Content-Digest']).toEqual(testBlobDigest);
 });
 
@@ -126,7 +128,7 @@ tap.test('OCI: should upload manifest (PUT /v2/{name}/manifests/{reference})', a
 
   const response = await registry.handleRequest({
     method: 'PUT',
-    path: '/oci/v2/test-repo/manifests/v1.0.0',
+    path: '/oci/test-repo/manifests/v1.0.0',
     headers: {
       Authorization: `Bearer ${ociToken}`,
       'Content-Type': 'application/vnd.oci.image.manifest.v1+json',
@@ -143,7 +145,7 @@ tap.test('OCI: should upload manifest (PUT /v2/{name}/manifests/{reference})', a
 tap.test('OCI: should retrieve manifest by tag (GET /v2/{name}/manifests/{reference})', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/manifests/v1.0.0',
+    path: '/oci/test-repo/manifests/v1.0.0',
     headers: {
       Authorization: `Bearer ${ociToken}`,
       Accept: 'application/vnd.oci.image.manifest.v1+json',
@@ -152,9 +154,10 @@ tap.test('OCI: should retrieve manifest by tag (GET /v2/{name}/manifests/{refere
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 
-  const manifest = JSON.parse((response.body as Buffer).toString('utf-8'));
+  const manifest = JSON.parse(body.toString('utf-8'));
   expect(manifest.schemaVersion).toEqual(2);
   expect(manifest.config.digest).toEqual(testConfigDigest);
   expect(manifest.layers[0].digest).toEqual(testBlobDigest);
@@ -163,7 +166,7 @@ tap.test('OCI: should retrieve manifest by tag (GET /v2/{name}/manifests/{refere
 tap.test('OCI: should retrieve manifest by digest (GET /v2/{name}/manifests/{digest})', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: `/oci/v2/test-repo/manifests/${testManifestDigest}`,
+    path: `/oci/test-repo/manifests/${testManifestDigest}`,
     headers: {
       Authorization: `Bearer ${ociToken}`,
       Accept: 'application/vnd.oci.image.manifest.v1+json',
@@ -178,7 +181,7 @@ tap.test('OCI: should retrieve manifest by digest (GET /v2/{name}/manifests/{dig
 tap.test('OCI: should check if manifest exists (HEAD /v2/{name}/manifests/{reference})', async () => {
   const response = await registry.handleRequest({
     method: 'HEAD',
-    path: '/oci/v2/test-repo/manifests/v1.0.0',
+    path: '/oci/test-repo/manifests/v1.0.0',
     headers: {
       Authorization: `Bearer ${ociToken}`,
       Accept: 'application/vnd.oci.image.manifest.v1+json',
@@ -193,7 +196,7 @@ tap.test('OCI: should check if manifest exists (HEAD /v2/{name}/manifests/{refer
 tap.test('OCI: should list tags (GET /v2/{name}/tags/list)', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/tags/list',
+    path: '/oci/test-repo/tags/list',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -201,9 +204,9 @@ tap.test('OCI: should list tags (GET /v2/{name}/tags/list)', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('tags');
+  const tagList = await streamToJson(response.body);
+  expect(tagList).toHaveProperty('tags');
 
-  const tagList = response.body as any;
   expect(tagList.name).toEqual('test-repo');
   expect(tagList.tags).toBeInstanceOf(Array);
   expect(tagList.tags).toContain('v1.0.0');
@@ -212,7 +215,7 @@ tap.test('OCI: should list tags (GET /v2/{name}/tags/list)', async () => {
 tap.test('OCI: should handle pagination for tag list', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/tags/list',
+    path: '/oci/test-repo/tags/list',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -222,13 +225,14 @@ tap.test('OCI: should handle pagination for tag list', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('tags');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('tags');
 });
 
 tap.test('OCI: should return 404 for non-existent blob', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/blobs/sha256:0000000000000000000000000000000000000000000000000000000000000000',
+    path: '/oci/test-repo/blobs/sha256:0000000000000000000000000000000000000000000000000000000000000000',
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -236,13 +240,14 @@ tap.test('OCI: should return 404 for non-existent blob', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('errors');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('errors');
 });
 
 tap.test('OCI: should return 404 for non-existent manifest', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/manifests/non-existent-tag',
+    path: '/oci/test-repo/manifests/non-existent-tag',
     headers: {
       Authorization: `Bearer ${ociToken}`,
       Accept: 'application/vnd.oci.image.manifest.v1+json',
@@ -251,13 +256,14 @@ tap.test('OCI: should return 404 for non-existent manifest', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('errors');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('errors');
 });
 
 tap.test('OCI: should delete manifest (DELETE /v2/{name}/manifests/{digest})', async () => {
   const response = await registry.handleRequest({
     method: 'DELETE',
-    path: `/oci/v2/test-repo/manifests/${testManifestDigest}`,
+    path: `/oci/test-repo/manifests/${testManifestDigest}`,
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -270,7 +276,7 @@ tap.test('OCI: should delete manifest (DELETE /v2/{name}/manifests/{digest})', a
 tap.test('OCI: should delete blob (DELETE /v2/{name}/blobs/{digest})', async () => {
   const response = await registry.handleRequest({
     method: 'DELETE',
-    path: `/oci/v2/test-repo/blobs/${testBlobDigest}`,
+    path: `/oci/test-repo/blobs/${testBlobDigest}`,
     headers: {
       Authorization: `Bearer ${ociToken}`,
     },
@@ -283,7 +289,7 @@ tap.test('OCI: should delete blob (DELETE /v2/{name}/blobs/{digest})', async ()
 tap.test('OCI: should handle unauthorized requests', async () => {
   const response = await registry.handleRequest({
     method: 'GET',
-    path: '/oci/v2/test-repo/manifests/v1.0.0',
+    path: '/oci/test-repo/manifests/v1.0.0',
     headers: {
       // No authorization header
     },

test/test.pypi.nativecli.node.ts

@@ -0,0 +1,515 @@
+/**
+ * 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, generateTestRunId } 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;
+
+// Unique test run ID to avoid conflicts between test runs
+const testRunId = generateTestRunId();
+const testPackageName = `test-pypi-pkg-${testRunId}`;
+
+/**
+ * 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 (response.body is always ReadableStream<Uint8Array> or undefined)
+        if (response.body) {
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
+        } 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 () => {
+  // Use port 39000 (avoids conflicts with other tests)
+  registryPort = 39000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
+  const tokens = await createTestTokens(registry);
+  pypiToken = tokens.pypiToken;
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(pypiToken).toBeTypeOf('string');
+  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 version = '1.0.0';
+  const wheelPath = await createTestWheelFile(testPackageName, 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 response = await fetch(`${registryUrl}/pypi/simple/${testPackageName}/`);
+  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 version = '1.1.0';
+  const sdistPath = await createTestSdistFile(testPackageName, 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 response = await fetch(`${registryUrl}/pypi/simple/${testPackageName}/`);
+  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 response = await fetch(`${registryUrl}/pypi/pypi/${testPackageName}/json`);
+  expect(response.status).toEqual(200);
+
+  const metadata = await response.json();
+  expect(metadata.info).toBeDefined();
+  expect(metadata.info.name).toEqual(testPackageName);
+  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 ${testPackageName}==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 () => {
+  if (!hasTwine) {
+    console.log('Skipping - twine not available (no packages uploaded)');
+    return;
+  }
+
+  // Use the JSON API to search/list
+  const response = await fetch(`${registryUrl}/pypi/pypi/${testPackageName}/json`);
+  expect(response.status).toEqual(200);
+
+  const metadata = await response.json();
+  expect(metadata.info.name).toEqual(testPackageName);
+});
+
+tap.test('PyPI CLI: should fail upload without auth', async () => {
+  if (!hasTwine) {
+    console.log('Skipping twine test - twine not available');
+    return;
+  }
+
+  const unauthPkgName = `unauth-pkg-${testRunId}`;
+  const version = '1.0.0';
+  const wheelPath = await createTestWheelFile(unauthPkgName, 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();

test/test.pypi.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import {
   createTestRegistry,
   createTestTokens,
@@ -101,9 +102,10 @@ tap.test('PyPI: should retrieve Simple API root index HTML (GET /simple/)', asyn
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toStartWith('text/html');
-  expect(response.body).toBeTypeOf('string');
+  const body = await streamToBuffer(response.body);
+  const html = body.toString('utf-8');
+  expect(html).toBeTypeOf('string');
 
-  const html = response.body as string;
   expect(html).toContain('<!DOCTYPE html>');
   expect(html).toContain('<title>Simple Index</title>');
   expect(html).toContain(normalizedPackageName);
@@ -121,9 +123,9 @@ tap.test('PyPI: should retrieve Simple API root index JSON (GET /simple/ with Ac
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/vnd.pypi.simple.v1+json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(json).toHaveProperty('meta');
   expect(json).toHaveProperty('projects');
   expect(json.projects).toBeInstanceOf(Array);
@@ -144,9 +146,10 @@ tap.test('PyPI: should retrieve Simple API package HTML (GET /simple/{package}/)
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toStartWith('text/html');
-  expect(response.body).toBeTypeOf('string');
+  const body = await streamToBuffer(response.body);
+  const html = body.toString('utf-8');
+  expect(html).toBeTypeOf('string');
 
-  const html = response.body as string;
   expect(html).toContain('<!DOCTYPE html>');
   expect(html).toContain(`<title>Links for ${normalizedPackageName}</title>`);
   expect(html).toContain('.whl');
@@ -165,9 +168,9 @@ tap.test('PyPI: should retrieve Simple API package JSON (GET /simple/{package}/
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/vnd.pypi.simple.v1+json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(json).toHaveProperty('meta');
   expect(json).toHaveProperty('name');
   expect(json.name).toEqual(normalizedPackageName);
@@ -187,8 +190,9 @@ tap.test('PyPI: should download wheel file (GET /pypi/packages/{package}/{filena
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).length).toEqual(testWheelData.length);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.length).toEqual(testWheelData.length);
   expect(response.headers['Content-Type']).toEqual('application/octet-stream');
 });
 
@@ -234,7 +238,7 @@ tap.test('PyPI: should list both wheel and sdist in Simple API', async () => {
 
   expect(response.status).toEqual(200);
 
-  const json = response.body as any;
+  const json = await streamToJson(response.body);
   // PEP 691: files is an array of file objects
   expect(json.files.length).toEqual(2);
 
@@ -289,7 +293,7 @@ tap.test('PyPI: should list multiple versions in Simple API', async () => {
 
   expect(response.status).toEqual(200);
 
-  const json = response.body as any;
+  const json = await streamToJson(response.body);
   // PEP 691: files is an array of file objects
   expect(json.files.length).toBeGreaterThan(2);
 
@@ -323,7 +327,8 @@ tap.test('PyPI: should return 404 for non-existent package', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('PyPI: should return 401 for unauthorized upload', async () => {
@@ -353,7 +358,8 @@ tap.test('PyPI: should return 401 for unauthorized upload', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('PyPI: should reject upload with mismatched hash', async () => {
@@ -382,7 +388,8 @@ tap.test('PyPI: should reject upload with mismatched hash', async () => {
   });
 
   expect(response.status).toEqual(400);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('PyPI: should handle package with requires-python metadata', async () => {
@@ -425,7 +432,8 @@ tap.test('PyPI: should handle package with requires-python metadata', async () =
     query: {},
   });
 
-  const html = getResponse.body as string;
+  const getBody = await streamToBuffer(getResponse.body);
+  const html = getBody.toString('utf-8');
   expect(html).toContain('data-requires-python');
   // Note: >= gets HTML-escaped to &gt;= in attribute values
   expect(html).toContain('&gt;=3.8');
@@ -441,9 +449,9 @@ tap.test('PyPI: should support JSON API for package metadata', async () => {
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(json).toHaveProperty('info');
   expect(json.info).toHaveProperty('name');
   expect(json.info.name).toEqual(normalizedPackageName);
@@ -460,9 +468,9 @@ tap.test('PyPI: should support JSON API for specific version', async () => {
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(json).toHaveProperty('info');
   expect(json.info.version).toEqual(testVersion);
   expect(json).toHaveProperty('urls');

test/test.rubygems.nativecli.node.ts

@@ -79,16 +79,10 @@ async function createHttpServer(
           res.setHeader(key, value);
         }
 
-        // Send body
+        // Send body (response.body is always ReadableStream<Uint8Array> or undefined)
         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));
-          }
+          const { Readable } = await import('stream');
+          Readable.fromWeb(response.body).pipe(res);
         } else {
           res.end();
         }
@@ -194,16 +188,16 @@ function cleanupTestDir(dir: string): void {
 // ========================================================================
 
 tap.test('RubyGems CLI: should setup registry and HTTP server', async () => {
-  // Create registry
-  registry = await createTestRegistry();
+  // Use port 36000 (avoids npm:35000, cargo:5000 conflicts)
+  registryPort = 36000;
+
+  // Create registry with correct registryUrl for CLI tests
+  registry = await createTestRegistry({ registryUrl: `http://localhost:${registryPort}` });
   const tokens = await createTestTokens(registry);
   rubygemsToken = tokens.rubygemsToken;
 
   expect(registry).toBeInstanceOf(SmartRegistry);
   expect(rubygemsToken).toBeTypeOf('string');
-
-  // Use port 36000 (avoids npm:35000, cargo:5000 conflicts)
-  registryPort = 36000;
   const serverSetup = await createHttpServer(registry, registryPort);
   server = serverSetup.server;
   registryUrl = serverSetup.url;

test/test.rubygems.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToBuffer, streamToJson } from '../ts/core/helpers.stream.js';
 import {
   createTestRegistry,
   createTestTokens,
@@ -54,7 +55,8 @@ tap.test('RubyGems: should upload gem file (POST /rubygems/api/v1/gems)', async
   });
 
   expect(response.status).toEqual(201);
-  expect(response.body).toHaveProperty('message');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('message');
 });
 
 tap.test('RubyGems: should retrieve Compact Index versions file (GET /rubygems/versions)', async () => {
@@ -67,9 +69,10 @@ tap.test('RubyGems: should retrieve Compact Index versions file (GET /rubygems/v
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('text/plain; charset=utf-8');
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const content = body.toString('utf-8');
   expect(content).toContain('created_at:');
   expect(content).toContain('---');
   expect(content).toContain(testGemName);
@@ -86,9 +89,10 @@ tap.test('RubyGems: should retrieve Compact Index info file (GET /rubygems/info/
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('text/plain; charset=utf-8');
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const content = body.toString('utf-8');
   expect(content).toContain('---');
   expect(content).toContain(testVersion);
   expect(content).toContain('checksum:');
@@ -104,9 +108,10 @@ tap.test('RubyGems: should retrieve Compact Index names file (GET /rubygems/name
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('text/plain; charset=utf-8');
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const content = body.toString('utf-8');
   expect(content).toContain('---');
   expect(content).toContain(testGemName);
 });
@@ -120,8 +125,9 @@ tap.test('RubyGems: should download gem file (GET /rubygems/gems/{gem}-{version}
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
-  expect((response.body as Buffer).length).toEqual(testGemData.length);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
+  expect(body.length).toEqual(testGemData.length);
   expect(response.headers['Content-Type']).toEqual('application/octet-stream');
 });
 
@@ -153,7 +159,8 @@ tap.test('RubyGems: should list multiple versions in Compact Index', async () =>
 
   expect(response.status).toEqual(200);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const body = await streamToBuffer(response.body);
+  const content = body.toString('utf-8');
   const lines = content.split('\n');
   const gemLine = lines.find(l => l.startsWith(`${testGemName} `));
 
@@ -172,7 +179,8 @@ tap.test('RubyGems: should list multiple versions in info file', async () => {
 
   expect(response.status).toEqual(200);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const body = await streamToBuffer(response.body);
+  const content = body.toString('utf-8');
   expect(content).toContain('1.0.0');
   expect(content).toContain('2.0.0');
 });
@@ -203,7 +211,8 @@ tap.test('RubyGems: should support platform-specific gems', async () => {
     query: {},
   });
 
-  const content = (versionsResponse.body as Buffer).toString('utf-8');
+  const versionsBody = await streamToBuffer(versionsResponse.body);
+  const content = versionsBody.toString('utf-8');
   const lines = content.split('\n');
   const gemLine = lines.find(l => l.startsWith(`${testGemName} `));
 
@@ -224,8 +233,9 @@ tap.test('RubyGems: should yank a gem version (DELETE /rubygems/api/v1/gems/yank
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('message');
-  expect((response.body as any).message).toContain('yanked');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('message');
+  expect(body.message).toContain('yanked');
 });
 
 tap.test('RubyGems: should mark yanked version in Compact Index', async () => {
@@ -238,7 +248,8 @@ tap.test('RubyGems: should mark yanked version in Compact Index', async () => {
 
   expect(response.status).toEqual(200);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const body = await streamToBuffer(response.body);
+  const content = body.toString('utf-8');
   const lines = content.split('\n');
   const gemLine = lines.find(l => l.startsWith(`${testGemName} `));
 
@@ -256,7 +267,8 @@ tap.test('RubyGems: should still allow downloading yanked gem', async () => {
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 });
 
 tap.test('RubyGems: should unyank a gem version (PUT /rubygems/api/v1/gems/unyank)', async () => {
@@ -273,8 +285,9 @@ tap.test('RubyGems: should unyank a gem version (PUT /rubygems/api/v1/gems/unyan
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toHaveProperty('message');
-  expect((response.body as any).message).toContain('unyanked');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('message');
+  expect(body.message).toContain('unyanked');
 });
 
 tap.test('RubyGems: should remove yank marker after unyank', async () => {
@@ -287,7 +300,8 @@ tap.test('RubyGems: should remove yank marker after unyank', async () => {
 
   expect(response.status).toEqual(200);
 
-  const content = (response.body as Buffer).toString('utf-8');
+  const body = await streamToBuffer(response.body);
+  const content = body.toString('utf-8');
   const lines = content.split('\n');
   const gemLine = lines.find(l => l.startsWith(`${testGemName} `));
 
@@ -309,9 +323,9 @@ tap.test('RubyGems: should retrieve versions JSON (GET /rubygems/api/v1/versions
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(json).toHaveProperty('name');
   expect(json.name).toEqual(testGemName);
   expect(json).toHaveProperty('versions');
@@ -331,9 +345,9 @@ tap.test('RubyGems: should retrieve dependencies JSON (GET /rubygems/api/v1/depe
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/json');
-  expect(response.body).toBeTypeOf('object');
+  const json = await streamToJson(response.body);
+  expect(json).toBeTypeOf('object');
 
-  const json = response.body as any;
   expect(Array.isArray(json)).toEqual(true);
 });
 
@@ -346,7 +360,8 @@ tap.test('RubyGems: should retrieve gem spec (GET /rubygems/quick/Marshal.4.8/{g
   });
 
   expect(response.status).toEqual(200);
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 });
 
 tap.test('RubyGems: should support latest specs endpoint (GET /rubygems/latest_specs.4.8.gz)', async () => {
@@ -359,7 +374,8 @@ tap.test('RubyGems: should support latest specs endpoint (GET /rubygems/latest_s
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/octet-stream');
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 });
 
 tap.test('RubyGems: should support specs endpoint (GET /rubygems/specs.4.8.gz)', async () => {
@@ -372,7 +388,8 @@ tap.test('RubyGems: should support specs endpoint (GET /rubygems/specs.4.8.gz)',
 
   expect(response.status).toEqual(200);
   expect(response.headers['Content-Type']).toEqual('application/octet-stream');
-  expect(response.body).toBeInstanceOf(Buffer);
+  const body = await streamToBuffer(response.body);
+  expect(body).toBeInstanceOf(Buffer);
 });
 
 tap.test('RubyGems: should return 404 for non-existent gem', async () => {
@@ -384,7 +401,8 @@ tap.test('RubyGems: should return 404 for non-existent gem', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('RubyGems: should return 401 for unauthorized upload', async () => {
@@ -402,7 +420,8 @@ tap.test('RubyGems: should return 401 for unauthorized upload', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('RubyGems: should return 401 for unauthorized yank', async () => {
@@ -419,7 +438,8 @@ tap.test('RubyGems: should return 401 for unauthorized yank', async () => {
   });
 
   expect(response.status).toEqual(401);
-  expect(response.body).toHaveProperty('error');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
 });
 
 tap.test('RubyGems: should handle gem with dependencies', async () => {
@@ -450,7 +470,8 @@ tap.test('RubyGems: should handle gem with dependencies', async () => {
 
   expect(infoResponse.status).toEqual(200);
 
-  const content = (infoResponse.body as Buffer).toString('utf-8');
+  const infoBody = await streamToBuffer(infoResponse.body);
+  const content = infoBody.toString('utf-8');
   expect(content).toContain('checksum:');
 });
 

test/test.storage.hooks.ts

@@ -0,0 +1,506 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as qenv from '@push.rocks/qenv';
+import { RegistryStorage } from '../ts/core/classes.registrystorage.js';
+import type { IStorageConfig } from '../ts/core/interfaces.core.js';
+import type { IStorageHooks, IStorageHookContext } from '../ts/core/interfaces.storage.js';
+import { createTrackingHooks, createQuotaHooks, generateTestRunId } from './helpers/registry.js';
+
+const testQenv = new qenv.Qenv('./', './.nogit');
+
+// ============================================================================
+// Test State
+// ============================================================================
+
+let storage: RegistryStorage;
+let storageConfig: IStorageConfig;
+let testRunId: string;
+
+// ============================================================================
+// Setup
+// ============================================================================
+
+tap.test('setup: should create storage config', async () => {
+  testRunId = generateTestRunId();
+
+  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');
+
+  storageConfig = {
+    accessKey: s3AccessKey || 'minioadmin',
+    accessSecret: s3SecretKey || 'minioadmin',
+    endpoint: s3Endpoint || 'localhost',
+    port: parseInt(s3Port || '9000', 10),
+    useSsl: false,
+    region: 'us-east-1',
+    bucketName: `test-hooks-${testRunId}`,
+  };
+
+  expect(storageConfig.bucketName).toBeTruthy();
+});
+
+// ============================================================================
+// beforePut Hook Tests
+// ============================================================================
+
+tap.test('beforePut: should be called before storage', async () => {
+  const tracker = createTrackingHooks();
+
+  storage = new RegistryStorage(storageConfig, tracker.hooks);
+  await storage.init();
+
+  // Set context and put object
+  storage.setContext({
+    protocol: 'npm',
+    actor: { userId: 'testuser' },
+    metadata: { packageName: 'test-package' },
+  });
+
+  await storage.putObject('test/beforeput-called.txt', Buffer.from('test data'));
+  storage.clearContext();
+
+  // Verify beforePut was called
+  const beforePutCalls = tracker.calls.filter(c => c.method === 'beforePut');
+  expect(beforePutCalls.length).toEqual(1);
+  expect(beforePutCalls[0].context.operation).toEqual('put');
+  expect(beforePutCalls[0].context.key).toEqual('test/beforeput-called.txt');
+  expect(beforePutCalls[0].context.protocol).toEqual('npm');
+});
+
+tap.test('beforePut: returning {allowed: false} should block storage', async () => {
+  const tracker = createTrackingHooks({ beforePutAllowed: false });
+
+  const blockingStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await blockingStorage.init();
+
+  blockingStorage.setContext({
+    protocol: 'npm',
+    actor: { userId: 'testuser' },
+  });
+
+  let errorThrown = false;
+  try {
+    await blockingStorage.putObject('test/should-not-exist.txt', Buffer.from('blocked data'));
+  } catch (error) {
+    errorThrown = true;
+    expect((error as Error).message).toContain('Blocked by test');
+  }
+
+  blockingStorage.clearContext();
+
+  expect(errorThrown).toBeTrue();
+
+  // Verify object was NOT stored
+  const result = await blockingStorage.getObject('test/should-not-exist.txt');
+  expect(result).toBeNull();
+});
+
+// ============================================================================
+// afterPut Hook Tests
+// ============================================================================
+
+tap.test('afterPut: should be called after successful storage', async () => {
+  const tracker = createTrackingHooks();
+
+  const trackedStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await trackedStorage.init();
+
+  trackedStorage.setContext({
+    protocol: 'maven',
+    actor: { userId: 'maven-user' },
+  });
+
+  await trackedStorage.putObject('test/afterput-test.txt', Buffer.from('after put test'));
+  trackedStorage.clearContext();
+
+  // Give async hook time to complete
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const afterPutCalls = tracker.calls.filter(c => c.method === 'afterPut');
+  expect(afterPutCalls.length).toEqual(1);
+  expect(afterPutCalls[0].context.operation).toEqual('put');
+});
+
+tap.test('afterPut: should receive correct metadata (size, key, protocol)', async () => {
+  const tracker = createTrackingHooks();
+
+  const metadataStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await metadataStorage.init();
+
+  const testData = Buffer.from('metadata test data - some content here');
+
+  metadataStorage.setContext({
+    protocol: 'cargo',
+    actor: { userId: 'cargo-user', ip: '192.168.1.100' },
+    metadata: { packageName: 'my-crate', version: '1.0.0' },
+  });
+
+  await metadataStorage.putObject('test/metadata-test.txt', testData);
+  metadataStorage.clearContext();
+
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const afterPutCalls = tracker.calls.filter(c => c.method === 'afterPut');
+  expect(afterPutCalls.length).toBeGreaterThanOrEqual(1);
+
+  const call = afterPutCalls[afterPutCalls.length - 1];
+  expect(call.context.metadata?.size).toEqual(testData.length);
+  expect(call.context.key).toEqual('test/metadata-test.txt');
+  expect(call.context.protocol).toEqual('cargo');
+  expect(call.context.actor?.userId).toEqual('cargo-user');
+  expect(call.context.actor?.ip).toEqual('192.168.1.100');
+});
+
+// ============================================================================
+// beforeDelete Hook Tests
+// ============================================================================
+
+tap.test('beforeDelete: should be called before deletion', async () => {
+  const tracker = createTrackingHooks();
+
+  const deleteStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await deleteStorage.init();
+
+  // First, store an object
+  deleteStorage.setContext({ protocol: 'npm' });
+  await deleteStorage.putObject('test/to-delete.txt', Buffer.from('delete me'));
+
+  // Now delete it
+  await deleteStorage.deleteObject('test/to-delete.txt');
+  deleteStorage.clearContext();
+
+  const beforeDeleteCalls = tracker.calls.filter(c => c.method === 'beforeDelete');
+  expect(beforeDeleteCalls.length).toEqual(1);
+  expect(beforeDeleteCalls[0].context.operation).toEqual('delete');
+  expect(beforeDeleteCalls[0].context.key).toEqual('test/to-delete.txt');
+});
+
+tap.test('beforeDelete: returning {allowed: false} should block deletion', async () => {
+  const tracker = createTrackingHooks({ beforeDeleteAllowed: false });
+
+  const protectedStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await protectedStorage.init();
+
+  // First store an object
+  protectedStorage.setContext({ protocol: 'npm' });
+  await protectedStorage.putObject('test/protected.txt', Buffer.from('protected data'));
+
+  // Try to delete - should be blocked
+  let errorThrown = false;
+  try {
+    await protectedStorage.deleteObject('test/protected.txt');
+  } catch (error) {
+    errorThrown = true;
+    expect((error as Error).message).toContain('Blocked by test');
+  }
+
+  protectedStorage.clearContext();
+
+  expect(errorThrown).toBeTrue();
+
+  // Verify object still exists
+  const result = await protectedStorage.getObject('test/protected.txt');
+  expect(result).toBeTruthy();
+});
+
+// ============================================================================
+// afterDelete Hook Tests
+// ============================================================================
+
+tap.test('afterDelete: should be called after successful deletion', async () => {
+  const tracker = createTrackingHooks();
+
+  const afterDeleteStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await afterDeleteStorage.init();
+
+  afterDeleteStorage.setContext({ protocol: 'pypi' });
+  await afterDeleteStorage.putObject('test/delete-tracked.txt', Buffer.from('to be deleted'));
+  await afterDeleteStorage.deleteObject('test/delete-tracked.txt');
+  afterDeleteStorage.clearContext();
+
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const afterDeleteCalls = tracker.calls.filter(c => c.method === 'afterDelete');
+  expect(afterDeleteCalls.length).toEqual(1);
+  expect(afterDeleteCalls[0].context.operation).toEqual('delete');
+});
+
+// ============================================================================
+// afterGet Hook Tests
+// ============================================================================
+
+tap.test('afterGet: should be called after reading object', async () => {
+  const tracker = createTrackingHooks();
+
+  const getStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await getStorage.init();
+
+  // Store an object first
+  getStorage.setContext({ protocol: 'rubygems' });
+  await getStorage.putObject('test/read-test.txt', Buffer.from('read me'));
+
+  // Clear calls to focus on the get
+  tracker.calls.length = 0;
+
+  // Read the object
+  const data = await getStorage.getObject('test/read-test.txt');
+  getStorage.clearContext();
+
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  expect(data).toBeTruthy();
+  expect(data!.toString()).toEqual('read me');
+
+  const afterGetCalls = tracker.calls.filter(c => c.method === 'afterGet');
+  expect(afterGetCalls.length).toEqual(1);
+  expect(afterGetCalls[0].context.operation).toEqual('get');
+});
+
+// ============================================================================
+// Context Tests
+// ============================================================================
+
+tap.test('context: hooks should receive actor information', async () => {
+  const tracker = createTrackingHooks();
+
+  const actorStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await actorStorage.init();
+
+  actorStorage.setContext({
+    protocol: 'composer',
+    actor: {
+      userId: 'user-123',
+      tokenId: 'token-abc',
+      ip: '10.0.0.1',
+      userAgent: 'composer/2.0',
+      orgId: 'org-456',
+      sessionId: 'session-xyz',
+    },
+  });
+
+  await actorStorage.putObject('test/actor-test.txt', Buffer.from('actor test'));
+  actorStorage.clearContext();
+
+  const beforePutCall = tracker.calls.find(c => c.method === 'beforePut');
+  expect(beforePutCall).toBeTruthy();
+  expect(beforePutCall!.context.actor?.userId).toEqual('user-123');
+  expect(beforePutCall!.context.actor?.tokenId).toEqual('token-abc');
+  expect(beforePutCall!.context.actor?.ip).toEqual('10.0.0.1');
+  expect(beforePutCall!.context.actor?.userAgent).toEqual('composer/2.0');
+  expect(beforePutCall!.context.actor?.orgId).toEqual('org-456');
+  expect(beforePutCall!.context.actor?.sessionId).toEqual('session-xyz');
+});
+
+tap.test('withContext: should set and clear context correctly', async () => {
+  const tracker = createTrackingHooks();
+
+  const contextStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await contextStorage.init();
+
+  // Use withContext to ensure automatic cleanup
+  await contextStorage.withContext(
+    {
+      protocol: 'oci',
+      actor: { userId: 'oci-user' },
+    },
+    async () => {
+      await contextStorage.putObject('test/with-context.txt', Buffer.from('context managed'));
+    }
+  );
+
+  const call = tracker.calls.find(c => c.method === 'beforePut');
+  expect(call).toBeTruthy();
+  expect(call!.context.protocol).toEqual('oci');
+  expect(call!.context.actor?.userId).toEqual('oci-user');
+});
+
+tap.test('withContext: should clear context even on error', async () => {
+  const tracker = createTrackingHooks({ beforePutAllowed: false });
+
+  const errorStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await errorStorage.init();
+
+  let errorThrown = false;
+  try {
+    await errorStorage.withContext(
+      {
+        protocol: 'npm',
+        actor: { userId: 'error-user' },
+      },
+      async () => {
+        await errorStorage.putObject('test/error-context.txt', Buffer.from('will fail'));
+      }
+    );
+  } catch {
+    errorThrown = true;
+  }
+
+  expect(errorThrown).toBeTrue();
+
+  // Verify context was cleared - next operation without context should work
+  // (hooks won't be called without context)
+  tracker.hooks.beforePut = async () => ({ allowed: true });
+  await errorStorage.putObject('test/after-error.txt', Buffer.from('ok'));
+});
+
+// ============================================================================
+// Graceful Degradation Tests
+// ============================================================================
+
+tap.test('graceful: hooks should not fail the operation if afterPut throws', async () => {
+  const tracker = createTrackingHooks({ throwOnAfterPut: true });
+
+  const gracefulStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await gracefulStorage.init();
+
+  gracefulStorage.setContext({ protocol: 'npm' });
+
+  // This should NOT throw even though afterPut throws
+  let errorThrown = false;
+  try {
+    await gracefulStorage.putObject('test/graceful-afterput.txt', Buffer.from('should succeed'));
+  } catch {
+    errorThrown = true;
+  }
+
+  gracefulStorage.clearContext();
+
+  expect(errorThrown).toBeFalse();
+
+  // Verify object was stored
+  const data = await gracefulStorage.getObject('test/graceful-afterput.txt');
+  expect(data).toBeTruthy();
+});
+
+tap.test('graceful: hooks should not fail the operation if afterGet throws', async () => {
+  const tracker = createTrackingHooks({ throwOnAfterGet: true });
+
+  const gracefulGetStorage = new RegistryStorage(storageConfig, tracker.hooks);
+  await gracefulGetStorage.init();
+
+  // Store first
+  gracefulGetStorage.setContext({ protocol: 'maven' });
+  await gracefulGetStorage.putObject('test/graceful-afterget.txt', Buffer.from('read me gracefully'));
+
+  // Read should succeed even though afterGet throws
+  let errorThrown = false;
+  try {
+    const data = await gracefulGetStorage.getObject('test/graceful-afterget.txt');
+    expect(data).toBeTruthy();
+  } catch {
+    errorThrown = true;
+  }
+
+  gracefulGetStorage.clearContext();
+
+  expect(errorThrown).toBeFalse();
+});
+
+// ============================================================================
+// Quota Hooks Tests
+// ============================================================================
+
+tap.test('quota: should block storage when quota exceeded', async () => {
+  const maxSize = 100; // 100 bytes max
+  const quotaTracker = createQuotaHooks(maxSize);
+
+  const quotaStorage = new RegistryStorage(storageConfig, quotaTracker.hooks);
+  await quotaStorage.init();
+
+  quotaStorage.setContext({
+    protocol: 'npm',
+    actor: { userId: 'quota-user' },
+  });
+
+  // Store 50 bytes - should succeed
+  await quotaStorage.putObject('test/quota-1.txt', Buffer.from('x'.repeat(50)));
+  expect(quotaTracker.currentUsage.bytes).toEqual(50);
+
+  // Try to store 60 more bytes - should fail (total would be 110)
+  let errorThrown = false;
+  try {
+    await quotaStorage.putObject('test/quota-2.txt', Buffer.from('x'.repeat(60)));
+  } catch (error) {
+    errorThrown = true;
+    expect((error as Error).message).toContain('Quota exceeded');
+  }
+
+  quotaStorage.clearContext();
+
+  expect(errorThrown).toBeTrue();
+  expect(quotaTracker.currentUsage.bytes).toEqual(50); // Still 50, not 110
+});
+
+tap.test('quota: should update usage after delete', async () => {
+  const maxSize = 200;
+  const quotaTracker = createQuotaHooks(maxSize);
+
+  const quotaDelStorage = new RegistryStorage(storageConfig, quotaTracker.hooks);
+  await quotaDelStorage.init();
+
+  quotaDelStorage.setContext({
+    protocol: 'npm',
+    metadata: { size: 75 },
+  });
+
+  // Store and track
+  await quotaDelStorage.putObject('test/quota-del.txt', Buffer.from('x'.repeat(75)));
+  expect(quotaTracker.currentUsage.bytes).toEqual(75);
+
+  // Delete and verify usage decreases
+  await quotaDelStorage.deleteObject('test/quota-del.txt');
+
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  quotaDelStorage.clearContext();
+
+  // Usage should be reduced (though exact value depends on metadata)
+  expect(quotaTracker.currentUsage.bytes).toBeLessThanOrEqual(75);
+});
+
+// ============================================================================
+// setHooks Tests
+// ============================================================================
+
+tap.test('setHooks: should allow setting hooks after construction', async () => {
+  const lateStorage = new RegistryStorage(storageConfig);
+  await lateStorage.init();
+
+  // Initially no hooks
+  await lateStorage.putObject('test/no-hooks.txt', Buffer.from('no hooks yet'));
+
+  // Add hooks later
+  const tracker = createTrackingHooks();
+  lateStorage.setHooks(tracker.hooks);
+
+  lateStorage.setContext({ protocol: 'npm' });
+  await lateStorage.putObject('test/with-late-hooks.txt', Buffer.from('now with hooks'));
+  lateStorage.clearContext();
+
+  const beforePutCalls = tracker.calls.filter(c => c.method === 'beforePut');
+  expect(beforePutCalls.length).toEqual(1);
+});
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+tap.test('cleanup: should clean up test bucket', async () => {
+  if (storage) {
+    // Clean up test objects
+    const prefixes = ['test/'];
+    for (const prefix of prefixes) {
+      try {
+        const objects = await storage.listObjects(prefix);
+        for (const obj of objects) {
+          await storage.deleteObject(obj);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.ts

@@ -1,5 +1,6 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
 import { SmartRegistry } from '../ts/index.js';
+import { streamToJson } from '../ts/core/helpers.stream.js';
 import { createTestRegistry, createTestTokens } from './helpers/registry.js';
 
 let registry: SmartRegistry;
@@ -54,8 +55,9 @@ tap.test('Integration: should return 404 for unknown paths', async () => {
   });
 
   expect(response.status).toEqual(404);
-  expect(response.body).toHaveProperty('error');
-  expect((response.body as any).error).toEqual('NOT_FOUND');
+  const body = await streamToJson(response.body);
+  expect(body).toHaveProperty('error');
+  expect(body.error).toEqual('NOT_FOUND');
 });
 
 tap.test('Integration: should create and validate tokens', async () => {

test/test.upstream.cache.s3.ts

@@ -0,0 +1,598 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as qenv from '@push.rocks/qenv';
+import * as smartbucket from '@push.rocks/smartbucket';
+import { UpstreamCache } from '../ts/upstream/classes.upstreamcache.js';
+import type { IUpstreamFetchContext, IUpstreamCacheConfig } from '../ts/upstream/interfaces.upstream.js';
+import type { IStorageBackend } from '../ts/core/interfaces.core.js';
+import { generateTestRunId } from './helpers/registry.js';
+
+const testQenv = new qenv.Qenv('./', './.nogit');
+
+// ============================================================================
+// Test State
+// ============================================================================
+
+let cache: UpstreamCache;
+let storageBackend: IStorageBackend;
+let s3Bucket: smartbucket.Bucket;
+let smartBucket: smartbucket.SmartBucket;
+let testRunId: string;
+let bucketName: string;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function createFetchContext(overrides?: Partial<IUpstreamFetchContext>): IUpstreamFetchContext {
+  // Use resource name as path to ensure unique cache keys
+  const resource = overrides?.resource || 'lodash';
+  return {
+    protocol: 'npm',
+    resource,
+    resourceType: 'packument',
+    path: `/${resource}`,
+    method: 'GET',
+    headers: {},
+    query: {},
+    ...overrides,
+  };
+}
+
+// ============================================================================
+// Setup
+// ============================================================================
+
+tap.test('setup: should create S3 storage backend', async () => {
+  testRunId = generateTestRunId();
+  bucketName = `test-ucache-${testRunId.substring(0, 8)}`;
+
+  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');
+
+  smartBucket = new smartbucket.SmartBucket({
+    accessKey: s3AccessKey || 'minioadmin',
+    accessSecret: s3SecretKey || 'minioadmin',
+    endpoint: s3Endpoint || 'localhost',
+    port: parseInt(s3Port || '9000', 10),
+    useSsl: false,
+  });
+
+  s3Bucket = await smartBucket.createBucket(bucketName);
+
+  // Create storage backend adapter
+  storageBackend = {
+    getObject: async (key: string): Promise<Buffer | null> => {
+      try {
+        // fastGet returns Buffer directly (or undefined if not found)
+        const data = await s3Bucket.fastGet({ path: key });
+        if (!data) {
+          return null;
+        }
+        return data;
+      } catch (error) {
+        // fastGet throws if object doesn't exist
+        return null;
+      }
+    },
+    putObject: async (key: string, data: Buffer): Promise<void> => {
+      await s3Bucket.fastPut({ path: key, contents: data, overwrite: true });
+    },
+    deleteObject: async (key: string): Promise<void> => {
+      await s3Bucket.fastRemove({ path: key });
+    },
+    listObjects: async (prefix: string): Promise<string[]> => {
+      const paths: string[] = [];
+      for await (const path of s3Bucket.listAllObjects(prefix)) {
+        paths.push(path);
+      }
+      return paths;
+    },
+  };
+
+  expect(storageBackend).toBeTruthy();
+});
+
+tap.test('setup: should create UpstreamCache with S3 storage', async () => {
+  cache = new UpstreamCache(
+    { enabled: true, defaultTtlSeconds: 300 },
+    10000,
+    storageBackend
+  );
+
+  expect(cache.isEnabled()).toBeTrue();
+  expect(cache.hasStorage()).toBeTrue();
+});
+
+// ============================================================================
+// Basic Cache Operations
+// ============================================================================
+
+tap.test('cache: should store cache entry in S3', async () => {
+  const context = createFetchContext({ resource: 'store-test' });
+  const testData = Buffer.from(JSON.stringify({ name: 'store-test', version: '1.0.0' }));
+  const upstreamUrl = 'https://registry.npmjs.org';
+
+  await cache.set(
+    context,
+    testData,
+    'application/json',
+    { 'etag': '"abc123"' },
+    'npmjs',
+    upstreamUrl
+  );
+
+  // Verify in S3
+  const stats = cache.getStats();
+  expect(stats.totalEntries).toBeGreaterThanOrEqual(1);
+});
+
+tap.test('cache: should retrieve cache entry from S3', async () => {
+  const context = createFetchContext({ resource: 'retrieve-test' });
+  const testData = Buffer.from('retrieve test data');
+  const upstreamUrl = 'https://registry.npmjs.org';
+
+  await cache.set(
+    context,
+    testData,
+    'application/octet-stream',
+    {},
+    'npmjs',
+    upstreamUrl
+  );
+
+  const entry = await cache.get(context, upstreamUrl);
+
+  expect(entry).toBeTruthy();
+  expect(entry!.data.toString()).toEqual('retrieve test data');
+  expect(entry!.contentType).toEqual('application/octet-stream');
+  expect(entry!.upstreamId).toEqual('npmjs');
+});
+
+// ============================================================================
+// Multi-Upstream URL Tests
+// ============================================================================
+
+tap.test('cache: should include upstream URL in cache path', async () => {
+  const context = createFetchContext({ resource: 'url-path-test' });
+  const testData = Buffer.from('url path test');
+
+  await cache.set(
+    context,
+    testData,
+    'text/plain',
+    {},
+    'npmjs',
+    'https://registry.npmjs.org'
+  );
+
+  // The cache key should include the escaped URL
+  const entry = await cache.get(context, 'https://registry.npmjs.org');
+  expect(entry).toBeTruthy();
+  expect(entry!.data.toString()).toEqual('url path test');
+});
+
+tap.test('cache: should handle multiple upstreams with different URLs', async () => {
+  const context = createFetchContext({ resource: '@company/private-pkg' });
+
+  // Store from private upstream
+  const privateData = Buffer.from('private package data');
+  await cache.set(
+    context,
+    privateData,
+    'application/json',
+    {},
+    'private-npm',
+    'https://npm.company.com'
+  );
+
+  // Store from public upstream (same resource name, different upstream)
+  const publicData = Buffer.from('public package data');
+  await cache.set(
+    context,
+    publicData,
+    'application/json',
+    {},
+    'public-npm',
+    'https://registry.npmjs.org'
+  );
+
+  // Retrieve from private - should get private data
+  const privateEntry = await cache.get(context, 'https://npm.company.com');
+  expect(privateEntry).toBeTruthy();
+  expect(privateEntry!.data.toString()).toEqual('private package data');
+  expect(privateEntry!.upstreamId).toEqual('private-npm');
+
+  // Retrieve from public - should get public data
+  const publicEntry = await cache.get(context, 'https://registry.npmjs.org');
+  expect(publicEntry).toBeTruthy();
+  expect(publicEntry!.data.toString()).toEqual('public package data');
+  expect(publicEntry!.upstreamId).toEqual('public-npm');
+});
+
+// ============================================================================
+// TTL and Expiration Tests
+// ============================================================================
+
+tap.test('cache: should respect TTL expiration', async () => {
+  // Create cache with very short TTL
+  const shortTtlCache = new UpstreamCache(
+    {
+      enabled: true,
+      defaultTtlSeconds: 1, // 1 second TTL
+      staleWhileRevalidate: false,
+      staleMaxAgeSeconds: 0,
+      immutableTtlSeconds: 1,
+      negativeCacheTtlSeconds: 1,
+    },
+    1000,
+    storageBackend
+  );
+
+  const context = createFetchContext({ resource: 'ttl-test' });
+  const testData = Buffer.from('expires soon');
+
+  await shortTtlCache.set(
+    context,
+    testData,
+    'text/plain',
+    {},
+    'test-upstream',
+    'https://test.example.com'
+  );
+
+  // Should exist immediately
+  let entry = await shortTtlCache.get(context, 'https://test.example.com');
+  expect(entry).toBeTruthy();
+
+  // Wait for expiration
+  await new Promise(resolve => setTimeout(resolve, 1500));
+
+  // Should be expired now
+  entry = await shortTtlCache.get(context, 'https://test.example.com');
+  expect(entry).toBeNull();
+
+  shortTtlCache.stop();
+});
+
+tap.test('cache: should serve stale content during stale-while-revalidate window', async () => {
+  const staleCache = new UpstreamCache(
+    {
+      enabled: true,
+      defaultTtlSeconds: 1, // 1 second fresh
+      staleWhileRevalidate: true,
+      staleMaxAgeSeconds: 60, // 60 seconds stale window
+      immutableTtlSeconds: 1,
+      negativeCacheTtlSeconds: 1,
+    },
+    1000,
+    storageBackend
+  );
+
+  const context = createFetchContext({ resource: 'stale-test' });
+  const testData = Buffer.from('stale but usable');
+
+  await staleCache.set(
+    context,
+    testData,
+    'text/plain',
+    {},
+    'stale-upstream',
+    'https://stale.example.com'
+  );
+
+  // Wait for fresh period to expire
+  await new Promise(resolve => setTimeout(resolve, 1500));
+
+  // Should still be available but marked as stale
+  const entry = await staleCache.get(context, 'https://stale.example.com');
+  expect(entry).toBeTruthy();
+  expect(entry!.stale).toBeTrue();
+  expect(entry!.data.toString()).toEqual('stale but usable');
+
+  staleCache.stop();
+});
+
+tap.test('cache: should reject content past stale deadline', async () => {
+  const veryShortCache = new UpstreamCache(
+    {
+      enabled: true,
+      defaultTtlSeconds: 1,
+      staleWhileRevalidate: true,
+      staleMaxAgeSeconds: 1, // Only 1 second stale window
+      immutableTtlSeconds: 1,
+      negativeCacheTtlSeconds: 1,
+    },
+    1000,
+    storageBackend
+  );
+
+  const context = createFetchContext({ resource: 'very-stale-test' });
+  await veryShortCache.set(
+    context,
+    Buffer.from('will expire completely'),
+    'text/plain',
+    {},
+    'short-upstream',
+    'https://short.example.com'
+  );
+
+  // Wait for both fresh AND stale periods to expire
+  await new Promise(resolve => setTimeout(resolve, 2500));
+
+  const entry = await veryShortCache.get(context, 'https://short.example.com');
+  expect(entry).toBeNull();
+
+  veryShortCache.stop();
+});
+
+// ============================================================================
+// Negative Cache Tests
+// ============================================================================
+
+tap.test('cache: should store negative cache entries (404)', async () => {
+  const context = createFetchContext({ resource: 'not-found-pkg' });
+  const upstreamUrl = 'https://registry.npmjs.org';
+
+  await cache.setNegative(context, 'npmjs', upstreamUrl);
+
+  const hasNegative = await cache.hasNegative(context, upstreamUrl);
+  expect(hasNegative).toBeTrue();
+});
+
+tap.test('cache: should retrieve negative cache entries', async () => {
+  const context = createFetchContext({ resource: 'negative-retrieve-test' });
+  const upstreamUrl = 'https://registry.npmjs.org';
+
+  await cache.setNegative(context, 'npmjs', upstreamUrl);
+
+  const entry = await cache.get(context, upstreamUrl);
+  expect(entry).toBeTruthy();
+  expect(entry!.data.length).toEqual(0); // Empty buffer indicates 404
+});
+
+// ============================================================================
+// Eviction Tests
+// ============================================================================
+
+tap.test('cache: should evict oldest entries when memory limit reached', async () => {
+  // Create cache with very small limit
+  const smallCache = new UpstreamCache(
+    { enabled: true, defaultTtlSeconds: 300 },
+    5, // Only 5 entries
+    storageBackend
+  );
+
+  // Add 10 entries
+  for (let i = 0; i < 10; i++) {
+    const context = createFetchContext({ resource: `evict-test-${i}` });
+    await smallCache.set(
+      context,
+      Buffer.from(`data ${i}`),
+      'text/plain',
+      {},
+      'evict-upstream',
+      'https://evict.example.com'
+    );
+  }
+
+  const stats = smallCache.getStats();
+  // Should have evicted some entries
+  expect(stats.totalEntries).toBeLessThanOrEqual(5);
+
+  smallCache.stop();
+});
+
+// ============================================================================
+// Query Parameter Tests
+// ============================================================================
+
+tap.test('cache: cache key should include query parameters', async () => {
+  const context1 = createFetchContext({
+    resource: 'query-test',
+    query: { version: '1.0.0' },
+  });
+
+  const context2 = createFetchContext({
+    resource: 'query-test',
+    query: { version: '2.0.0' },
+  });
+
+  const upstreamUrl = 'https://registry.npmjs.org';
+
+  // Store with v1 query
+  await cache.set(
+    context1,
+    Buffer.from('version 1 data'),
+    'text/plain',
+    {},
+    'query-upstream',
+    upstreamUrl
+  );
+
+  // Store with v2 query
+  await cache.set(
+    context2,
+    Buffer.from('version 2 data'),
+    'text/plain',
+    {},
+    'query-upstream',
+    upstreamUrl
+  );
+
+  // Retrieve v1 - should get v1 data
+  const entry1 = await cache.get(context1, upstreamUrl);
+  expect(entry1).toBeTruthy();
+  expect(entry1!.data.toString()).toEqual('version 1 data');
+
+  // Retrieve v2 - should get v2 data
+  const entry2 = await cache.get(context2, upstreamUrl);
+  expect(entry2).toBeTruthy();
+  expect(entry2!.data.toString()).toEqual('version 2 data');
+});
+
+// ============================================================================
+// S3 Persistence Tests
+// ============================================================================
+
+tap.test('cache: should load from S3 on memory cache miss', async () => {
+  // Use a unique resource name for this test
+  const uniqueResource = `persist-test-${Date.now()}`;
+  const persistContext = createFetchContext({ resource: uniqueResource });
+  const upstreamUrl = 'https://persist.example.com';
+
+  // Store in first cache instance
+  await cache.set(
+    persistContext,
+    Buffer.from('persisted data'),
+    'text/plain',
+    {},
+    'persist-upstream',
+    upstreamUrl
+  );
+
+  // Wait for S3 write to complete
+  await new Promise(resolve => setTimeout(resolve, 200));
+
+  // Verify the entry is in the original cache's memory
+  const originalEntry = await cache.get(persistContext, upstreamUrl);
+  expect(originalEntry).toBeTruthy();
+
+  // Create a new cache instance (simulates restart) with SAME storage backend
+  const freshCache = new UpstreamCache(
+    { enabled: true, defaultTtlSeconds: 300 },
+    10000,
+    storageBackend
+  );
+
+  // Fresh cache has empty memory, should load from S3
+  const entry = await freshCache.get(persistContext, upstreamUrl);
+
+  expect(entry).toBeTruthy();
+  expect(entry!.data.toString()).toEqual('persisted data');
+
+  freshCache.stop();
+});
+
+// ============================================================================
+// Cache Stats Tests
+// ============================================================================
+
+tap.test('cache: should return accurate stats', async () => {
+  const statsCache = new UpstreamCache(
+    { enabled: true, defaultTtlSeconds: 300 },
+    1000,
+    storageBackend
+  );
+
+  // Add some entries
+  for (let i = 0; i < 3; i++) {
+    const context = createFetchContext({ resource: `stats-test-${i}` });
+    await statsCache.set(
+      context,
+      Buffer.from(`stats data ${i}`),
+      'text/plain',
+      {},
+      'stats-upstream',
+      'https://stats.example.com'
+    );
+  }
+
+  // Add a negative entry
+  const negContext = createFetchContext({ resource: 'stats-negative' });
+  await statsCache.setNegative(negContext, 'stats-upstream', 'https://stats.example.com');
+
+  const stats = statsCache.getStats();
+
+  expect(stats.totalEntries).toBeGreaterThanOrEqual(4);
+  expect(stats.enabled).toBeTrue();
+  expect(stats.hasStorage).toBeTrue();
+  expect(stats.maxEntries).toEqual(1000);
+
+  statsCache.stop();
+});
+
+// ============================================================================
+// Invalidation Tests
+// ============================================================================
+
+tap.test('cache: should invalidate specific cache entry', async () => {
+  const invalidateContext = createFetchContext({ resource: 'invalidate-test' });
+  const upstreamUrl = 'https://invalidate.example.com';
+
+  await cache.set(
+    invalidateContext,
+    Buffer.from('to be invalidated'),
+    'text/plain',
+    {},
+    'inv-upstream',
+    upstreamUrl
+  );
+
+  // Verify it exists
+  let entry = await cache.get(invalidateContext, upstreamUrl);
+  expect(entry).toBeTruthy();
+
+  // Invalidate
+  const deleted = await cache.invalidate(invalidateContext, upstreamUrl);
+  expect(deleted).toBeTrue();
+
+  // Should be gone
+  entry = await cache.get(invalidateContext, upstreamUrl);
+  expect(entry).toBeNull();
+});
+
+tap.test('cache: should invalidate entries matching pattern', async () => {
+  const upstreamUrl = 'https://pattern.example.com';
+
+  // Add multiple entries
+  for (const name of ['pattern-a', 'pattern-b', 'other-c']) {
+    const context = createFetchContext({ resource: name });
+    await cache.set(
+      context,
+      Buffer.from(`data for ${name}`),
+      'text/plain',
+      {},
+      'pattern-upstream',
+      upstreamUrl
+    );
+  }
+
+  // Invalidate entries matching 'pattern-*'
+  const count = await cache.invalidatePattern(/pattern-/);
+  expect(count).toBeGreaterThanOrEqual(2);
+
+  // pattern-a should be gone
+  const entryA = await cache.get(createFetchContext({ resource: 'pattern-a' }), upstreamUrl);
+  expect(entryA).toBeNull();
+
+  // other-c should still exist
+  const entryC = await cache.get(createFetchContext({ resource: 'other-c' }), upstreamUrl);
+  expect(entryC).toBeTruthy();
+});
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+tap.test('cleanup: should stop cache and clean up bucket', async () => {
+  if (cache) {
+    cache.stop();
+  }
+
+  // Clean up test bucket
+  if (s3Bucket) {
+    try {
+      const files = await s3Bucket.fastList({});
+      for (const file of files) {
+        await s3Bucket.fastRemove({ path: file.name });
+      }
+      await smartBucket.removeBucket(bucketName);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+});
+
+export default tap.start();

test/test.upstream.provider.ts

@@ -0,0 +1,343 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { SmartRegistry } from '../ts/index.js';
+import {
+  createTestRegistryWithUpstream,
+  createTrackingUpstreamProvider,
+} from './helpers/registry.js';
+import { StaticUpstreamProvider } from '../ts/upstream/interfaces.upstream.js';
+import type {
+  IUpstreamProvider,
+  IUpstreamResolutionContext,
+  IProtocolUpstreamConfig,
+} from '../ts/upstream/interfaces.upstream.js';
+import type { TRegistryProtocol } from '../ts/core/interfaces.core.js';
+
+// =============================================================================
+// StaticUpstreamProvider Tests
+// =============================================================================
+
+tap.test('StaticUpstreamProvider: should return config for configured protocol', async () => {
+  const npmConfig: IProtocolUpstreamConfig = {
+    enabled: true,
+    upstreams: [{ id: 'npmjs', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+  };
+
+  const provider = new StaticUpstreamProvider({
+    npm: npmConfig,
+  });
+
+  const result = await provider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: 'lodash',
+    scope: null,
+    method: 'GET',
+    resourceType: 'packument',
+  });
+
+  expect(result).toBeDefined();
+  expect(result?.enabled).toEqual(true);
+  expect(result?.upstreams[0].id).toEqual('npmjs');
+});
+
+tap.test('StaticUpstreamProvider: should return null for unconfigured protocol', async () => {
+  const provider = new StaticUpstreamProvider({
+    npm: {
+      enabled: true,
+      upstreams: [{ id: 'npmjs', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+    },
+  });
+
+  const result = await provider.resolveUpstreamConfig({
+    protocol: 'maven',
+    resource: 'com.example:lib',
+    scope: 'com.example',
+    method: 'GET',
+    resourceType: 'pom',
+  });
+
+  expect(result).toBeNull();
+});
+
+tap.test('StaticUpstreamProvider: should support multiple protocols', async () => {
+  const provider = new StaticUpstreamProvider({
+    npm: {
+      enabled: true,
+      upstreams: [{ id: 'npmjs', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+    },
+    oci: {
+      enabled: true,
+      upstreams: [{ id: 'dockerhub', url: 'https://registry-1.docker.io', priority: 1, enabled: true }],
+    },
+    maven: {
+      enabled: true,
+      upstreams: [{ id: 'central', url: 'https://repo1.maven.org/maven2', priority: 1, enabled: true }],
+    },
+  });
+
+  const npmResult = await provider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: 'lodash',
+    scope: null,
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(npmResult?.upstreams[0].id).toEqual('npmjs');
+
+  const ociResult = await provider.resolveUpstreamConfig({
+    protocol: 'oci',
+    resource: 'library/nginx',
+    scope: 'library',
+    method: 'GET',
+    resourceType: 'manifest',
+  });
+  expect(ociResult?.upstreams[0].id).toEqual('dockerhub');
+
+  const mavenResult = await provider.resolveUpstreamConfig({
+    protocol: 'maven',
+    resource: 'com.example:lib',
+    scope: 'com.example',
+    method: 'GET',
+    resourceType: 'pom',
+  });
+  expect(mavenResult?.upstreams[0].id).toEqual('central');
+});
+
+// =============================================================================
+// Registry with Provider Integration Tests
+// =============================================================================
+
+let registry: SmartRegistry;
+let trackingProvider: ReturnType<typeof createTrackingUpstreamProvider>;
+
+tap.test('Provider Integration: should create registry with upstream provider', async () => {
+  trackingProvider = createTrackingUpstreamProvider({
+    npm: {
+      enabled: true,
+      upstreams: [{ id: 'test-npm', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+    },
+  });
+
+  registry = await createTestRegistryWithUpstream(trackingProvider.provider);
+
+  expect(registry).toBeInstanceOf(SmartRegistry);
+  expect(registry.isInitialized()).toEqual(true);
+});
+
+tap.test('Provider Integration: should call provider when fetching unknown npm package', async () => {
+  // Clear previous calls
+  trackingProvider.calls.length = 0;
+
+  // Request a package that doesn't exist locally - should trigger upstream lookup
+  const response = await registry.handleRequest({
+    method: 'GET',
+    path: '/npm/@test-scope/nonexistent-package',
+    headers: {},
+    query: {},
+  });
+
+  // Provider should have been called for the packument lookup
+  const npmCalls = trackingProvider.calls.filter(c => c.protocol === 'npm');
+
+  // The package doesn't exist locally, so upstream should be consulted
+  // Note: actual upstream fetch may fail since the package doesn't exist
+  expect(response.status).toBeOneOf([404, 200, 502]); // 404 if not found, 502 if upstream error
+});
+
+tap.test('Provider Integration: provider receives correct context for scoped npm package', async () => {
+  trackingProvider.calls.length = 0;
+
+  // Use URL-encoded path for scoped packages as npm client does
+  await registry.handleRequest({
+    method: 'GET',
+    path: '/npm/@myorg%2fmy-package',
+    headers: {},
+    query: {},
+  });
+
+  // Find any npm call - the exact resource type depends on routing
+  const npmCalls = trackingProvider.calls.filter(c => c.protocol === 'npm');
+
+  // Provider should be called for upstream lookup
+  if (npmCalls.length > 0) {
+    const call = npmCalls[0];
+    expect(call.protocol).toEqual('npm');
+    // The resource should include the scoped name
+    expect(call.resource).toInclude('myorg');
+    expect(call.method).toEqual('GET');
+  }
+});
+
+tap.test('Provider Integration: provider receives correct context for unscoped npm package', async () => {
+  trackingProvider.calls.length = 0;
+
+  await registry.handleRequest({
+    method: 'GET',
+    path: '/npm/lodash',
+    headers: {},
+    query: {},
+  });
+
+  const packumentCall = trackingProvider.calls.find(
+    c => c.protocol === 'npm' && c.resourceType === 'packument'
+  );
+
+  if (packumentCall) {
+    expect(packumentCall.protocol).toEqual('npm');
+    expect(packumentCall.resource).toEqual('lodash');
+    expect(packumentCall.scope).toBeNull(); // No scope for unscoped package
+  }
+});
+
+// =============================================================================
+// Custom Provider Implementation Tests
+// =============================================================================
+
+tap.test('Custom Provider: should support dynamic resolution based on context', async () => {
+  // Create a provider that returns different configs based on scope
+  const dynamicProvider: IUpstreamProvider = {
+    async resolveUpstreamConfig(context: IUpstreamResolutionContext) {
+      if (context.scope === 'internal') {
+        // Internal packages go to private registry
+        return {
+          enabled: true,
+          upstreams: [{ id: 'private', url: 'https://private.registry.com', priority: 1, enabled: true }],
+        };
+      }
+      // Everything else goes to public registry
+      return {
+        enabled: true,
+        upstreams: [{ id: 'public', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+      };
+    },
+  };
+
+  const internalResult = await dynamicProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: '@internal/utils',
+    scope: 'internal',
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(internalResult?.upstreams[0].id).toEqual('private');
+
+  const publicResult = await dynamicProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: '@public/utils',
+    scope: 'public',
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(publicResult?.upstreams[0].id).toEqual('public');
+});
+
+tap.test('Custom Provider: should support actor-based resolution', async () => {
+  const actorAwareProvider: IUpstreamProvider = {
+    async resolveUpstreamConfig(context: IUpstreamResolutionContext) {
+      // Different upstreams based on user's organization
+      if (context.actor?.orgId === 'enterprise-org') {
+        return {
+          enabled: true,
+          upstreams: [{ id: 'enterprise', url: 'https://enterprise.registry.com', priority: 1, enabled: true }],
+        };
+      }
+      return {
+        enabled: true,
+        upstreams: [{ id: 'default', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+      };
+    },
+  };
+
+  const enterpriseResult = await actorAwareProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: 'lodash',
+    scope: null,
+    actor: { orgId: 'enterprise-org', userId: 'user1' },
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(enterpriseResult?.upstreams[0].id).toEqual('enterprise');
+
+  const defaultResult = await actorAwareProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: 'lodash',
+    scope: null,
+    actor: { orgId: 'free-org', userId: 'user2' },
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(defaultResult?.upstreams[0].id).toEqual('default');
+});
+
+tap.test('Custom Provider: should support disabling upstream for specific resources', async () => {
+  const selectiveProvider: IUpstreamProvider = {
+    async resolveUpstreamConfig(context: IUpstreamResolutionContext) {
+      // Block upstream for internal packages
+      if (context.scope === 'internal') {
+        return null; // No upstream for internal packages
+      }
+      return {
+        enabled: true,
+        upstreams: [{ id: 'public', url: 'https://registry.npmjs.org', priority: 1, enabled: true }],
+      };
+    },
+  };
+
+  const internalResult = await selectiveProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: '@internal/secret',
+    scope: 'internal',
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(internalResult).toBeNull();
+
+  const publicResult = await selectiveProvider.resolveUpstreamConfig({
+    protocol: 'npm',
+    resource: 'lodash',
+    scope: null,
+    method: 'GET',
+    resourceType: 'packument',
+  });
+  expect(publicResult).not.toBeNull();
+});
+
+// =============================================================================
+// Registry without Provider Tests
+// =============================================================================
+
+tap.test('No Provider: registry should work without upstream provider', async () => {
+  const registryWithoutUpstream = await createTestRegistryWithUpstream(
+    // Pass a provider that always returns null
+    {
+      async resolveUpstreamConfig() {
+        return null;
+      },
+    }
+  );
+
+  expect(registryWithoutUpstream).toBeInstanceOf(SmartRegistry);
+
+  // Should return 404 for non-existent package (no upstream to check)
+  const response = await registryWithoutUpstream.handleRequest({
+    method: 'GET',
+    path: '/npm/nonexistent-package-xyz',
+    headers: {},
+    query: {},
+  });
+
+  expect(response.status).toEqual(404);
+
+  registryWithoutUpstream.destroy();
+});
+
+// =============================================================================
+// Cleanup
+// =============================================================================
+
+tap.postTask('cleanup registry', async () => {
+  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.2.0',
+  version: '2.8.0',
   description: 'A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries'
 }

ts/cargo/classes.cargoregistry.ts

@@ -2,7 +2,8 @@ import { Smartlog } from '@push.rocks/smartlog';
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
 import type {
   ICargoIndexEntry,
   ICargoPublishMetadata,
@@ -13,6 +14,7 @@ import type {
   ICargoSearchResponse,
   ICargoSearchResult,
 } from './interfaces.cargo.js';
+import { CargoUpstream } from './classes.cargoupstream.js';
 
 /**
  * Cargo/crates.io registry implementation
@@ -25,18 +27,21 @@ export class CargoRegistry extends BaseRegistry {
   private basePath: string = '/cargo';
   private registryUrl: string;
   private logger: Smartlog;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/cargo',
-    registryUrl: string = 'http://localhost:5000/cargo'
+    registryUrl: string = 'http://localhost:5000/cargo',
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
 
     // Initialize logger
     this.logger = new Smartlog({
@@ -52,6 +57,38 @@ export class CargoRegistry extends BaseRegistry {
     this.logger.enableConsole();
   }
 
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<CargoUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'cargo',
+      resource,
+      scope: resource, // For Cargo, crate name is the scope
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new CargoUpstream(config, undefined, this.logger);
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    // No persistent upstream to clean up with dynamic provider
+  }
+
   public async init(): Promise<void> {
     // Initialize config.json if not exists
     const existingConfig = await this.storage.getCargoConfig();
@@ -76,6 +113,14 @@ export class CargoRegistry extends BaseRegistry {
     const authHeader = context.headers['authorization'] || context.headers['Authorization'];
     const token = authHeader ? await this.authManager.validateToken(authHeader, 'cargo') : null;
 
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     this.logger.log('debug', `handleRequest: ${context.method} ${path}`, {
       method: context.method,
       path,
@@ -89,11 +134,11 @@ export class CargoRegistry extends BaseRegistry {
 
     // API endpoints
     if (path.startsWith('/api/v1/')) {
-      return this.handleApiRequest(path, context, token);
+      return this.handleApiRequest(path, context, token, actor);
     }
 
     // Index files (sparse protocol)
-    return this.handleIndexRequest(path);
+    return this.handleIndexRequest(path, actor);
   }
 
   /**
@@ -114,7 +159,8 @@ export class CargoRegistry extends BaseRegistry {
   private async handleApiRequest(
     path: string,
     context: IRequestContext,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     // Publish: PUT /api/v1/crates/new
     if (path === '/api/v1/crates/new' && context.method === 'PUT') {
@@ -124,7 +170,7 @@ export class CargoRegistry extends BaseRegistry {
     // Download: GET /api/v1/crates/{crate}/{version}/download
     const downloadMatch = path.match(/^\/api\/v1\/crates\/([^\/]+)\/([^\/]+)\/download$/);
     if (downloadMatch && context.method === 'GET') {
-      return this.handleDownload(downloadMatch[1], downloadMatch[2]);
+      return this.handleDownload(downloadMatch[1], downloadMatch[2], actor);
     }
 
     // Yank: DELETE /api/v1/crates/{crate}/{version}/yank
@@ -157,7 +203,7 @@ export class CargoRegistry extends BaseRegistry {
    * Handle index file requests
    * Paths: /1/{name}, /2/{name}, /3/{c}/{name}, /{p1}/{p2}/{name}
    */
-  private async handleIndexRequest(path: string): Promise<IResponse> {
+  private async handleIndexRequest(path: string, actor?: IRequestActor): Promise<IResponse> {
     // Parse index paths to extract crate name
     const pathParts = path.split('/').filter(p => p);
     let crateName: string | null = null;
@@ -184,7 +230,7 @@ export class CargoRegistry extends BaseRegistry {
       };
     }
 
-    return this.handleIndexFile(crateName);
+    return this.handleIndexFile(crateName, actor);
   }
 
   /**
@@ -206,8 +252,29 @@ export class CargoRegistry extends BaseRegistry {
   /**
    * Serve index file for a crate
    */
-  private async handleIndexFile(crateName: string): Promise<IResponse> {
-    const index = await this.storage.getCargoIndex(crateName);
+  private async handleIndexFile(crateName: string, actor?: IRequestActor): Promise<IResponse> {
+    let index = await this.storage.getCargoIndex(crateName);
+
+    // Try upstream if not found locally
+    if (!index || index.length === 0) {
+      const upstream = await this.getUpstreamForRequest(crateName, 'index', 'GET', actor);
+      if (upstream) {
+        const upstreamIndex = await upstream.fetchCrateIndex(crateName);
+        if (upstreamIndex) {
+          // Parse the newline-delimited JSON
+          const parsedIndex: ICargoIndexEntry[] = upstreamIndex
+            .split('\n')
+            .filter(line => line.trim())
+            .map(line => JSON.parse(line));
+
+          if (parsedIndex.length > 0) {
+            // Cache locally
+            await this.storage.putCargoIndex(crateName, parsedIndex);
+            index = parsedIndex;
+          }
+        }
+      }
+    }
 
     if (!index || index.length === 0) {
       return {
@@ -303,7 +370,7 @@ export class CargoRegistry extends BaseRegistry {
       const parsed = this.parsePublishRequest(body);
       metadata = parsed.metadata;
       crateFile = parsed.crateFile;
-    } catch (error) {
+    } catch (error: any) {
       this.logger.log('error', 'handlePublish: parse error', { error: error.message });
       return {
         status: 400,
@@ -395,11 +462,36 @@ export class CargoRegistry extends BaseRegistry {
    */
   private async handleDownload(
     crateName: string,
-    version: string
+    version: string,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     this.logger.log('debug', 'handleDownload', { crate: crateName, version });
 
-    const crateFile = await this.storage.getCargoCrate(crateName, version);
+    // Try streaming from local storage first
+    const streamResult = await this.storage.getCargoCrateStream(crateName, version);
+
+    if (streamResult) {
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/gzip',
+          'Content-Length': streamResult.size.toString(),
+          'Content-Disposition': `attachment; filename="${crateName}-${version}.crate"`,
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // Try upstream if not found locally
+    let crateFile: Buffer | null = null;
+    const upstream = await this.getUpstreamForRequest(crateName, 'crate', 'GET', actor);
+    if (upstream) {
+      crateFile = await upstream.fetchCrate(crateName, version);
+      if (crateFile) {
+        // Cache locally
+        await this.storage.putCargoCrate(crateName, version, crateFile);
+      }
+    }
 
     if (!crateFile) {
       return {
@@ -567,7 +659,7 @@ export class CargoRegistry extends BaseRegistry {
           }
         }
       }
-    } catch (error) {
+    } catch (error: any) {
       this.logger.log('error', 'handleSearch: error', { error: error.message });
     }
 

ts/cargo/classes.cargoupstream.ts

@@ -0,0 +1,159 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+
+/**
+ * Cargo-specific upstream implementation.
+ *
+ * Handles:
+ * - Crate metadata (index) fetching
+ * - Crate file (.crate) downloading
+ * - Sparse index protocol support
+ * - Content-addressable caching for .crate files
+ */
+export class CargoUpstream extends BaseUpstream {
+  protected readonly protocolName = 'cargo';
+
+  /** Base URL for crate downloads (may differ from index URL) */
+  private readonly downloadUrl: string;
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    downloadUrl?: string,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+    // Default to crates.io download URL if not specified
+    this.downloadUrl = downloadUrl || 'https://static.crates.io/crates';
+  }
+
+  /**
+   * Fetch crate metadata from the sparse index.
+   */
+  public async fetchCrateIndex(crateName: string): Promise<string | null> {
+    const path = this.buildIndexPath(crateName);
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'index',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'text/plain',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch a crate file from upstream.
+   */
+  public async fetchCrate(crateName: string, version: string): Promise<Buffer | null> {
+    // Crate downloads typically go to a different URL than the index
+    const path = `/${crateName}/${crateName}-${version}.crate`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'crate',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    // Use special handling for crate downloads
+    const result = await this.fetchCrateFile(crateName, version);
+    return result;
+  }
+
+  /**
+   * Fetch crate file directly from the download URL.
+   */
+  private async fetchCrateFile(crateName: string, version: string): Promise<Buffer | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'crate',
+      path: `/${crateName}/${crateName}-${version}.crate`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Build the sparse index path for a crate.
+   *
+   * Path structure:
+   * - 1 char: /1/{name}
+   * - 2 chars: /2/{name}
+   * - 3 chars: /3/{first char}/{name}
+   * - 4+ chars: /{first 2}/{next 2}/{name}
+   */
+  private buildIndexPath(crateName: string): string {
+    const lowerName = crateName.toLowerCase();
+    const len = lowerName.length;
+
+    if (len === 1) {
+      return `/1/${lowerName}`;
+    } else if (len === 2) {
+      return `/2/${lowerName}`;
+    } else if (len === 3) {
+      return `/3/${lowerName[0]}/${lowerName}`;
+    } else {
+      return `/${lowerName.slice(0, 2)}/${lowerName.slice(2, 4)}/${lowerName}`;
+    }
+  }
+
+  /**
+   * Override URL building for Cargo-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // For crate downloads, use the download URL
+    if (context.resourceType === 'crate') {
+      baseUrl = this.downloadUrl;
+    }
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/cargo/index.ts

@@ -3,4 +3,5 @@
  */
 
 export { CargoRegistry } from './classes.cargoregistry.js';
+export { CargoUpstream } from './classes.cargoupstream.js';
 export * from './interfaces.cargo.js';

ts/classes.smartregistry.ts

@@ -2,6 +2,7 @@ import { RegistryStorage } from './core/classes.registrystorage.js';
 import { AuthManager } from './core/classes.authmanager.js';
 import { BaseRegistry } from './core/classes.baseregistry.js';
 import type { IRegistryConfig, IRequestContext, IResponse } from './core/interfaces.core.js';
+import { toReadableStream } from './core/helpers.stream.js';
 import { OciRegistry } from './oci/classes.ociregistry.js';
 import { NpmRegistry } from './npm/classes.npmregistry.js';
 import { MavenRegistry } from './maven/classes.mavenregistry.js';
@@ -11,8 +12,39 @@ import { PypiRegistry } from './pypi/classes.pypiregistry.js';
 import { RubyGemsRegistry } from './rubygems/classes.rubygemsregistry.js';
 
 /**
- * Main registry orchestrator
- * Routes requests to appropriate protocol handlers (OCI, NPM, Maven, Cargo, Composer, PyPI, or RubyGems)
+ * Main registry orchestrator.
+ * Routes requests to appropriate protocol handlers (OCI, NPM, Maven, Cargo, Composer, PyPI, or RubyGems).
+ *
+ * Supports pluggable authentication and storage hooks:
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default in-memory auth
+ * const registry = new SmartRegistry(config);
+ *
+ * // With custom auth provider (LDAP, OAuth, etc.)
+ * const registry = new SmartRegistry({
+ *   ...config,
+ *   authProvider: new LdapAuthProvider(ldapClient),
+ * });
+ *
+ * // With storage hooks for quota tracking
+ * const registry = new SmartRegistry({
+ *   ...config,
+ *   storageHooks: {
+ *     beforePut: async (ctx) => {
+ *       const quota = await getQuota(ctx.actor?.orgId);
+ *       if (ctx.metadata?.size > quota) {
+ *         return { allowed: false, reason: 'Quota exceeded' };
+ *       }
+ *       return { allowed: true };
+ *     },
+ *     afterPut: async (ctx) => {
+ *       await auditLog('storage.put', ctx);
+ *     }
+ *   }
+ * });
+ * ```
  */
 export class SmartRegistry {
   private storage: RegistryStorage;
@@ -23,8 +55,12 @@ export class SmartRegistry {
 
   constructor(config: IRegistryConfig) {
     this.config = config;
-    this.storage = new RegistryStorage(config.storage);
-    this.authManager = new AuthManager(config.auth);
+
+    // Create storage with optional hooks
+    this.storage = new RegistryStorage(config.storage, config.storageHooks);
+
+    // Create auth manager with optional custom provider
+    this.authManager = new AuthManager(config.auth, config.authProvider);
   }
 
   /**
@@ -46,7 +82,13 @@ export class SmartRegistry {
         realm: this.config.auth.ociTokens.realm,
         service: this.config.auth.ociTokens.service,
       } : undefined;
-      const ociRegistry = new OciRegistry(this.storage, this.authManager, ociBasePath, ociTokens);
+      const ociRegistry = new OciRegistry(
+        this.storage,
+        this.authManager,
+        ociBasePath,
+        ociTokens,
+        this.config.upstreamProvider
+      );
       await ociRegistry.init();
       this.registries.set('oci', ociRegistry);
     }
@@ -54,8 +96,14 @@ export class SmartRegistry {
     // Initialize NPM registry if enabled
     if (this.config.npm?.enabled) {
       const npmBasePath = this.config.npm.basePath ?? '/npm';
-      const registryUrl = `http://localhost:5000${npmBasePath}`; // TODO: Make configurable
-      const npmRegistry = new NpmRegistry(this.storage, this.authManager, npmBasePath, registryUrl);
+      const registryUrl = this.config.npm.registryUrl ?? `http://localhost:5000${npmBasePath}`;
+      const npmRegistry = new NpmRegistry(
+        this.storage,
+        this.authManager,
+        npmBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await npmRegistry.init();
       this.registries.set('npm', npmRegistry);
     }
@@ -63,8 +111,14 @@ export class SmartRegistry {
     // Initialize Maven registry if enabled
     if (this.config.maven?.enabled) {
       const mavenBasePath = this.config.maven.basePath ?? '/maven';
-      const registryUrl = `http://localhost:5000${mavenBasePath}`; // TODO: Make configurable
-      const mavenRegistry = new MavenRegistry(this.storage, this.authManager, mavenBasePath, registryUrl);
+      const registryUrl = this.config.maven.registryUrl ?? `http://localhost:5000${mavenBasePath}`;
+      const mavenRegistry = new MavenRegistry(
+        this.storage,
+        this.authManager,
+        mavenBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await mavenRegistry.init();
       this.registries.set('maven', mavenRegistry);
     }
@@ -72,8 +126,14 @@ export class SmartRegistry {
     // Initialize Cargo registry if enabled
     if (this.config.cargo?.enabled) {
       const cargoBasePath = this.config.cargo.basePath ?? '/cargo';
-      const registryUrl = `http://localhost:5000${cargoBasePath}`; // TODO: Make configurable
-      const cargoRegistry = new CargoRegistry(this.storage, this.authManager, cargoBasePath, registryUrl);
+      const registryUrl = this.config.cargo.registryUrl ?? `http://localhost:5000${cargoBasePath}`;
+      const cargoRegistry = new CargoRegistry(
+        this.storage,
+        this.authManager,
+        cargoBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await cargoRegistry.init();
       this.registries.set('cargo', cargoRegistry);
     }
@@ -81,8 +141,14 @@ export class SmartRegistry {
     // Initialize Composer registry if enabled
     if (this.config.composer?.enabled) {
       const composerBasePath = this.config.composer.basePath ?? '/composer';
-      const registryUrl = `http://localhost:5000${composerBasePath}`; // TODO: Make configurable
-      const composerRegistry = new ComposerRegistry(this.storage, this.authManager, composerBasePath, registryUrl);
+      const registryUrl = this.config.composer.registryUrl ?? `http://localhost:5000${composerBasePath}`;
+      const composerRegistry = new ComposerRegistry(
+        this.storage,
+        this.authManager,
+        composerBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await composerRegistry.init();
       this.registries.set('composer', composerRegistry);
     }
@@ -90,8 +156,14 @@ export class SmartRegistry {
     // Initialize PyPI registry if enabled
     if (this.config.pypi?.enabled) {
       const pypiBasePath = this.config.pypi.basePath ?? '/pypi';
-      const registryUrl = `http://localhost:5000`; // TODO: Make configurable
-      const pypiRegistry = new PypiRegistry(this.storage, this.authManager, pypiBasePath, registryUrl);
+      const registryUrl = this.config.pypi.registryUrl ?? `http://localhost:5000`;
+      const pypiRegistry = new PypiRegistry(
+        this.storage,
+        this.authManager,
+        pypiBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await pypiRegistry.init();
       this.registries.set('pypi', pypiRegistry);
     }
@@ -99,8 +171,14 @@ export class SmartRegistry {
     // Initialize RubyGems registry if enabled
     if (this.config.rubygems?.enabled) {
       const rubygemsBasePath = this.config.rubygems.basePath ?? '/rubygems';
-      const registryUrl = `http://localhost:5000${rubygemsBasePath}`; // TODO: Make configurable
-      const rubygemsRegistry = new RubyGemsRegistry(this.storage, this.authManager, rubygemsBasePath, registryUrl);
+      const registryUrl = this.config.rubygems.registryUrl ?? `http://localhost:5000${rubygemsBasePath}`;
+      const rubygemsRegistry = new RubyGemsRegistry(
+        this.storage,
+        this.authManager,
+        rubygemsBasePath,
+        registryUrl,
+        this.config.upstreamProvider
+      );
       await rubygemsRegistry.init();
       this.registries.set('rubygems', rubygemsRegistry);
     }
@@ -114,75 +192,88 @@ export class SmartRegistry {
    */
   public async handleRequest(context: IRequestContext): Promise<IResponse> {
     const path = context.path;
+    let response: IResponse | undefined;
 
     // Route to OCI registry
-    if (this.config.oci?.enabled && path.startsWith(this.config.oci.basePath)) {
+    if (!response && this.config.oci?.enabled && path.startsWith(this.config.oci.basePath)) {
       const ociRegistry = this.registries.get('oci');
       if (ociRegistry) {
-        return ociRegistry.handleRequest(context);
+        response = await ociRegistry.handleRequest(context);
       }
     }
 
     // Route to NPM registry
-    if (this.config.npm?.enabled && path.startsWith(this.config.npm.basePath)) {
+    if (!response && this.config.npm?.enabled && path.startsWith(this.config.npm.basePath)) {
       const npmRegistry = this.registries.get('npm');
       if (npmRegistry) {
-        return npmRegistry.handleRequest(context);
+        response = await npmRegistry.handleRequest(context);
       }
     }
 
     // Route to Maven registry
-    if (this.config.maven?.enabled && path.startsWith(this.config.maven.basePath)) {
+    if (!response && this.config.maven?.enabled && path.startsWith(this.config.maven.basePath)) {
       const mavenRegistry = this.registries.get('maven');
       if (mavenRegistry) {
-        return mavenRegistry.handleRequest(context);
+        response = await mavenRegistry.handleRequest(context);
       }
     }
 
     // Route to Cargo registry
-    if (this.config.cargo?.enabled && path.startsWith(this.config.cargo.basePath)) {
+    if (!response && this.config.cargo?.enabled && path.startsWith(this.config.cargo.basePath)) {
       const cargoRegistry = this.registries.get('cargo');
       if (cargoRegistry) {
-        return cargoRegistry.handleRequest(context);
+        response = await cargoRegistry.handleRequest(context);
       }
     }
 
     // Route to Composer registry
-    if (this.config.composer?.enabled && path.startsWith(this.config.composer.basePath)) {
+    if (!response && this.config.composer?.enabled && path.startsWith(this.config.composer.basePath)) {
       const composerRegistry = this.registries.get('composer');
       if (composerRegistry) {
-        return composerRegistry.handleRequest(context);
+        response = await composerRegistry.handleRequest(context);
       }
     }
 
     // Route to PyPI registry (also handles /simple prefix)
-    if (this.config.pypi?.enabled) {
+    if (!response && this.config.pypi?.enabled) {
       const pypiBasePath = this.config.pypi.basePath ?? '/pypi';
       if (path.startsWith(pypiBasePath) || path.startsWith('/simple')) {
         const pypiRegistry = this.registries.get('pypi');
         if (pypiRegistry) {
-          return pypiRegistry.handleRequest(context);
+          response = await pypiRegistry.handleRequest(context);
         }
       }
     }
 
     // Route to RubyGems registry
-    if (this.config.rubygems?.enabled && path.startsWith(this.config.rubygems.basePath)) {
+    if (!response && this.config.rubygems?.enabled && path.startsWith(this.config.rubygems.basePath)) {
       const rubygemsRegistry = this.registries.get('rubygems');
       if (rubygemsRegistry) {
-        return rubygemsRegistry.handleRequest(context);
+        response = await rubygemsRegistry.handleRequest(context);
       }
     }
 
     // No matching registry
-    return {
-      status: 404,
-      headers: { 'Content-Type': 'application/json' },
-      body: {
-        error: 'NOT_FOUND',
-        message: 'No registry handler for this path',
-      },
-    };
+    if (!response) {
+      response = {
+        status: 404,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'NOT_FOUND',
+          message: 'No registry handler for this path',
+        },
+      };
+    }
+
+    // Normalize body to ReadableStream<Uint8Array> at the API boundary
+    if (response.body != null && !(response.body instanceof ReadableStream)) {
+      if (!Buffer.isBuffer(response.body) && typeof response.body === 'object' && !(response.body instanceof Uint8Array)) {
+        response.headers['Content-Type'] ??= 'application/json';
+      }
+      response.body = toReadableStream(response.body);
+    }
+
+    return response;
   }
 
   /**

ts/composer/classes.composerregistry.ts

@@ -6,7 +6,9 @@
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import { isBinaryData, toBuffer } from '../core/helpers.buffer.js';
 import type {
   IComposerPackage,
   IComposerPackageMetadata,
@@ -21,24 +23,73 @@ import {
   generatePackagesJson,
   sortVersions,
 } from './helpers.composer.js';
+import { ComposerUpstream } from './classes.composerupstream.js';
 
 export class ComposerRegistry extends BaseRegistry {
   private storage: RegistryStorage;
   private authManager: AuthManager;
   private basePath: string = '/composer';
   private registryUrl: string;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/composer',
-    registryUrl: string = 'http://localhost:5000/composer'
+    registryUrl: string = 'http://localhost:5000/composer',
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
+  }
+
+  /**
+   * Extract scope from Composer package name.
+   * For Composer, vendor is the scope.
+   * @example "symfony" from "symfony/console"
+   */
+  private extractScope(vendorPackage: string): string | null {
+    const slashIndex = vendorPackage.indexOf('/');
+    if (slashIndex > 0) {
+      return vendorPackage.substring(0, slashIndex);
+    }
+    return null;
+  }
+
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<ComposerUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'composer',
+      resource,
+      scope: this.extractScope(resource),
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new ComposerUpstream(config);
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    // No persistent upstream to clean up with dynamic provider
   }
 
   public async init(): Promise<void> {
@@ -77,6 +128,14 @@ export class ComposerRegistry extends BaseRegistry {
       }
     }
 
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     // Root packages.json
     if (path === '/packages.json' || path === '' || path === '/') {
       return this.handlePackagesJson();
@@ -87,7 +146,7 @@ export class ComposerRegistry extends BaseRegistry {
     if (metadataMatch) {
       const [, vendorPackage, devSuffix] = metadataMatch;
       const includeDev = !!devSuffix;
-      return this.handlePackageMetadata(vendorPackage, includeDev, token);
+      return this.handlePackageMetadata(vendorPackage, includeDev, token, actor);
     }
 
     // Package list: /packages/list.json?filter=vendor/*
@@ -157,10 +216,33 @@ export class ComposerRegistry extends BaseRegistry {
   private async handlePackageMetadata(
     vendorPackage: string,
     includeDev: boolean,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     // Read operations are public, no authentication required
-    const metadata = await this.storage.getComposerPackageMetadata(vendorPackage);
+    let metadata = await this.storage.getComposerPackageMetadata(vendorPackage);
+
+    // Try upstream if not found locally
+    if (!metadata) {
+      const upstream = await this.getUpstreamForRequest(vendorPackage, 'metadata', 'GET', actor);
+      if (upstream) {
+        const [vendor, packageName] = vendorPackage.split('/');
+        if (vendor && packageName) {
+          const upstreamMetadata = includeDev
+            ? await upstream.fetchPackageDevMetadata(vendor, packageName)
+            : await upstream.fetchPackageMetadata(vendor, packageName);
+
+          if (upstreamMetadata && upstreamMetadata.packages) {
+            // Store upstream metadata locally
+            metadata = {
+              packages: upstreamMetadata.packages,
+              lastModified: new Date().toUTCString(),
+            };
+            await this.storage.putComposerPackageMetadata(vendorPackage, metadata);
+          }
+        }
+      }
+    }
 
     if (!metadata) {
       return {
@@ -220,9 +302,9 @@ export class ComposerRegistry extends BaseRegistry {
     token: IAuthToken | null
   ): Promise<IResponse> {
     // Read operations are public, no authentication required
-    const zipData = await this.storage.getComposerPackageZip(vendorPackage, reference);
+    const streamResult = await this.storage.getComposerPackageZipStream(vendorPackage, reference);
 
-    if (!zipData) {
+    if (!streamResult) {
       return {
         status: 404,
         headers: {},
@@ -234,10 +316,10 @@ export class ComposerRegistry extends BaseRegistry {
       status: 200,
       headers: {
         'Content-Type': 'application/zip',
-        'Content-Length': zipData.length.toString(),
+        'Content-Length': streamResult.size.toString(),
         'Content-Disposition': `attachment; filename="${reference}.zip"`,
       },
-      body: zipData,
+      body: streamResult.stream,
     };
   }
 
@@ -255,7 +337,7 @@ export class ComposerRegistry extends BaseRegistry {
       };
     }
 
-    if (!body || !Buffer.isBuffer(body)) {
+    if (!body || !isBinaryData(body)) {
       return {
         status: 400,
         headers: {},
@@ -263,8 +345,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 +377,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/composer/classes.composerupstream.ts

@@ -0,0 +1,200 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+
+/**
+ * Composer-specific upstream implementation.
+ *
+ * Handles:
+ * - Package metadata fetching (packages.json, provider-includes)
+ * - Package version metadata (p2/{vendor}/{package}.json)
+ * - Dist file (zip) proxying
+ * - Packagist v2 API support
+ */
+export class ComposerUpstream extends BaseUpstream {
+  protected readonly protocolName = 'composer';
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+  }
+
+  /**
+   * Fetch the root packages.json from upstream.
+   */
+  public async fetchPackagesJson(): Promise<any | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'composer',
+      resource: '*',
+      resourceType: 'root',
+      path: '/packages.json',
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch package metadata using v2 API (p2/{vendor}/{package}.json).
+   */
+  public async fetchPackageMetadata(vendor: string, packageName: string): Promise<any | null> {
+    const fullName = `${vendor}/${packageName}`;
+    const path = `/p2/${vendor}/${packageName}.json`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'composer',
+      resource: fullName,
+      resourceType: 'metadata',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch package metadata with dev versions (p2/{vendor}/{package}~dev.json).
+   */
+  public async fetchPackageDevMetadata(vendor: string, packageName: string): Promise<any | null> {
+    const fullName = `${vendor}/${packageName}`;
+    const path = `/p2/${vendor}/${packageName}~dev.json`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'composer',
+      resource: fullName,
+      resourceType: 'metadata-dev',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch a provider-includes file.
+   */
+  public async fetchProviderIncludes(path: string): Promise<any | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'composer',
+      resource: '*',
+      resourceType: 'provider',
+      path: path.startsWith('/') ? path : `/${path}`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch a dist file (zip) from upstream.
+   */
+  public async fetchDist(url: string): Promise<Buffer | null> {
+    // Parse the URL to get the path
+    let path: string;
+    try {
+      const parsed = new URL(url);
+      path = parsed.pathname;
+    } catch {
+      path = url;
+    }
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'composer',
+      resource: '*',
+      resourceType: 'dist',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/zip, application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Override URL building for Composer-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/composer/index.ts

@@ -4,5 +4,6 @@
  */
 
 export { ComposerRegistry } from './classes.composerregistry.js';
+export { ComposerUpstream } from './classes.composerupstream.js';
 export * from './interfaces.composer.js';
 export * from './helpers.composer.js';

ts/core/classes.authmanager.ts

@@ -1,55 +1,79 @@
 import type { IAuthConfig, IAuthToken, ICredentials, TRegistryProtocol } from './interfaces.core.js';
-import * as crypto from 'crypto';
+import type { IAuthProvider, ITokenOptions } from './interfaces.auth.js';
+import { DefaultAuthProvider } from './classes.defaultauthprovider.js';
 
 /**
- * Unified authentication manager for all registry protocols
- * Handles both NPM UUID tokens and OCI JWT tokens
+ * Unified authentication manager for all registry protocols.
+ * Delegates to a pluggable IAuthProvider for actual auth operations.
+ *
+ * @example
+ * ```typescript
+ * // Use default in-memory provider
+ * const auth = new AuthManager(config);
+ *
+ * // Use custom provider (LDAP, OAuth, etc.)
+ * const auth = new AuthManager(config, new LdapAuthProvider(ldapClient));
+ * ```
  */
 export class AuthManager {
-  private tokenStore: Map<string, IAuthToken> = new Map();
-  private userCredentials: Map<string, string> = new Map(); // username -> password hash (mock)
+  private provider: IAuthProvider;
 
-  constructor(private config: IAuthConfig) {}
+  constructor(
+    private config: IAuthConfig,
+    provider?: IAuthProvider
+  ) {
+    // Use provided provider or default in-memory implementation
+    this.provider = provider || new DefaultAuthProvider(config);
+  }
 
   /**
    * Initialize the auth manager
    */
   public async init(): Promise<void> {
-    // Initialize token store (in-memory for now)
-    // In production, this could be Redis or a database
+    if (this.provider.init) {
+      await this.provider.init();
+    }
   }
 
   // ========================================================================
-  // UUID TOKEN CREATION (Base method for NPM, Maven, etc.)
+  // UNIFIED AUTHENTICATION (Delegated to Provider)
   // ========================================================================
 
   /**
-   * Create a UUID-based token with custom scopes (base method)
-   * @param userId - User ID
-   * @param protocol - Protocol type
-   * @param scopes - Permission scopes
-   * @param readonly - Whether the token is readonly
-   * @returns UUID token string
+   * Authenticate user credentials
+   * @param credentials - Username and password
+   * @returns User ID or null
    */
-  private async createUuidToken(
-    userId: string,
-    protocol: TRegistryProtocol,
-    scopes: string[],
-    readonly: boolean = false
-  ): Promise<string> {
-    const token = this.generateUuid();
-    const authToken: IAuthToken = {
-      type: protocol,
-      userId,
-      scopes,
-      readonly,
-      metadata: {
-        created: new Date().toISOString(),
-      },
-    };
+  public async authenticate(credentials: ICredentials): Promise<string | null> {
+    return this.provider.authenticate(credentials);
+  }
 
-    this.tokenStore.set(token, authToken);
-    return token;
+  /**
+   * Validate any token (NPM, Maven, OCI, PyPI, RubyGems, Composer, Cargo)
+   * @param tokenString - Token string (UUID or JWT)
+   * @param protocol - Expected protocol type (optional, improves performance)
+   * @returns Auth token object or null
+   */
+  public async validateToken(
+    tokenString: string,
+    protocol?: TRegistryProtocol
+  ): Promise<IAuthToken | null> {
+    return this.provider.validateToken(tokenString, protocol);
+  }
+
+  /**
+   * Check if token has permission for an action
+   * @param token - Auth token (or null for anonymous)
+   * @param resource - Resource being accessed (e.g., "npm:package:foo")
+   * @param action - Action being performed (read, write, push, pull, delete)
+   * @returns true if authorized
+   */
+  public async authorize(
+    token: IAuthToken | null,
+    resource: string,
+    action: string
+  ): Promise<boolean> {
+    return this.provider.authorize(token, resource, action);
   }
 
   // ========================================================================
@@ -66,9 +90,7 @@ export class AuthManager {
     if (!this.config.npmTokens.enabled) {
       throw new Error('NPM tokens are not enabled');
     }
-
-    const scopes = readonly ? ['npm:*:*:read'] : ['npm:*:*:*'];
-    return this.createUuidToken(userId, 'npm', scopes, readonly);
+    return this.provider.createToken(userId, 'npm', { readonly });
   }
 
   /**
@@ -77,22 +99,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateNpmToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'npm');
   }
 
   /**
@@ -100,7 +107,7 @@ export class AuthManager {
    * @param token - NPM UUID token
    */
   public async revokeNpmToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.provider.revokeToken(token);
   }
 
   /**
@@ -112,20 +119,12 @@ export class AuthManager {
     key: string;
     readonly: boolean;
     created: string;
+    protocol?: TRegistryProtocol;
   }>> {
-    const tokens: Array<{key: string; readonly: boolean; created: string}> = [];
-
-    for (const [token, authToken] of this.tokenStore.entries()) {
-      if (authToken.userId === userId) {
-        tokens.push({
-          key: this.hashToken(token),
-          readonly: authToken.readonly || false,
-          created: authToken.metadata?.created || 'unknown',
-        });
-      }
+    if (this.provider.listUserTokens) {
+      return this.provider.listUserTokens(userId);
     }
-
-    return tokens;
+    return [];
   }
 
   // ========================================================================
@@ -137,39 +136,17 @@ export class AuthManager {
    * @param userId - User ID
    * @param scopes - Permission scopes
    * @param expiresIn - Expiration time in seconds
-   * @returns JWT token string (HMAC-SHA256 signed)
+   * @returns JWT token string
    */
   public async createOciToken(
     userId: string,
     scopes: string[],
     expiresIn: number = 3600
   ): Promise<string> {
-    if (!this.config.ociTokens.enabled) {
+    if (!this.config.ociTokens?.enabled) {
       throw new Error('OCI tokens are not enabled');
     }
-
-    const now = Math.floor(Date.now() / 1000);
-    const payload = {
-      iss: this.config.ociTokens.realm,
-      sub: userId,
-      aud: this.config.ociTokens.service,
-      exp: now + expiresIn,
-      nbf: now,
-      iat: now,
-      access: this.scopesToOciAccess(scopes),
-    };
-
-    // Create JWT with HMAC-SHA256 signature
-    const header = { alg: 'HS256', typ: 'JWT' };
-    const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
-    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
-
-    const signature = crypto
-      .createHmac('sha256', this.config.jwtSecret)
-      .update(`${headerB64}.${payloadB64}`)
-      .digest('base64url');
-
-    return `${headerB64}.${payloadB64}.${signature}`;
+    return this.provider.createToken(userId, 'oci', { scopes, expiresIn });
   }
 
   /**
@@ -178,80 +155,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateOciToken(jwt: string): Promise<IAuthToken | null> {
-    try {
-      const parts = jwt.split('.');
-      if (parts.length !== 3) {
-        return null;
-      }
-
-      const [headerB64, payloadB64, signatureB64] = parts;
-
-      // Verify signature
-      const expectedSignature = crypto
-        .createHmac('sha256', this.config.jwtSecret)
-        .update(`${headerB64}.${payloadB64}`)
-        .digest('base64url');
-
-      if (signatureB64 !== expectedSignature) {
-        return null;
-      }
-
-      // Decode and parse payload
-      const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf-8'));
-
-      // Check expiration
-      const now = Math.floor(Date.now() / 1000);
-      if (payload.exp && payload.exp < now) {
-        return null;
-      }
-
-      // Check not-before time
-      if (payload.nbf && payload.nbf > now) {
-        return null;
-      }
-
-      // Convert to unified token format
-      const scopes = this.ociAccessToScopes(payload.access || []);
-
-      return {
-        type: 'oci',
-        userId: payload.sub,
-        scopes,
-        expiresAt: payload.exp ? new Date(payload.exp * 1000) : undefined,
-        metadata: {
-          iss: payload.iss,
-          aud: payload.aud,
-        },
-      };
-    } catch (error) {
-      return null;
-    }
-  }
-
-  // ========================================================================
-  // UNIFIED AUTHENTICATION
-  // ========================================================================
-
-  /**
-   * Authenticate user credentials
-   * @param credentials - Username and password
-   * @returns User ID or null
-   */
-  public async authenticate(credentials: ICredentials): Promise<string | null> {
-    // Mock authentication - in production, verify against database
-    const storedPassword = this.userCredentials.get(credentials.username);
-
-    if (!storedPassword) {
-      // Auto-register for testing (remove in production)
-      this.userCredentials.set(credentials.username, credentials.password);
-      return credentials.username;
-    }
-
-    if (storedPassword === credentials.password) {
-      return credentials.username;
-    }
-
-    return null;
+    return this.provider.validateToken(jwt, 'oci');
   }
 
   // ========================================================================
@@ -265,8 +169,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.createUuidToken(userId, 'maven', scopes, readonly);
+    return this.provider.createToken(userId, 'maven', { readonly });
   }
 
   /**
@@ -275,22 +178,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateMavenToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'maven');
   }
 
   /**
@@ -298,7 +186,7 @@ export class AuthManager {
    * @param token - Maven UUID token
    */
   public async revokeMavenToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.provider.revokeToken(token);
   }
 
   // ========================================================================
@@ -312,8 +200,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.createUuidToken(userId, 'composer', scopes, readonly);
+    return this.provider.createToken(userId, 'composer', { readonly });
   }
 
   /**
@@ -322,22 +209,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateComposerToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'composer');
   }
 
   /**
@@ -345,7 +217,7 @@ export class AuthManager {
    * @param token - Composer UUID token
    */
   public async revokeComposerToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.provider.revokeToken(token);
   }
 
   // ========================================================================
@@ -359,8 +231,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.createUuidToken(userId, 'cargo', scopes, readonly);
+    return this.provider.createToken(userId, 'cargo', { readonly });
   }
 
   /**
@@ -369,22 +240,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateCargoToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'cargo');
   }
 
   /**
@@ -392,7 +248,7 @@ export class AuthManager {
    * @param token - Cargo UUID token
    */
   public async revokeCargoToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.provider.revokeToken(token);
   }
 
   // ========================================================================
@@ -406,8 +262,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.createUuidToken(userId, 'pypi', scopes, readonly);
+    return this.provider.createToken(userId, 'pypi', { readonly });
   }
 
   /**
@@ -416,22 +271,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validatePypiToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'pypi');
   }
 
   /**
@@ -439,7 +279,7 @@ export class AuthManager {
    * @param token - PyPI UUID token
    */
   public async revokePypiToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
+    return this.provider.revokeToken(token);
   }
 
   // ========================================================================
@@ -453,8 +293,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.createUuidToken(userId, 'rubygems', scopes, readonly);
+    return this.provider.createToken(userId, 'rubygems', { readonly });
   }
 
   /**
@@ -463,22 +302,7 @@ export class AuthManager {
    * @returns Auth token object or null
    */
   public async validateRubyGemsToken(token: string): Promise<IAuthToken | null> {
-    if (!this.isValidUuid(token)) {
-      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;
+    return this.provider.validateToken(token, 'rubygems');
   }
 
   /**
@@ -486,226 +310,6 @@ export class AuthManager {
    * @param token - RubyGems UUID token
    */
   public async revokeRubyGemsToken(token: string): Promise<void> {
-    this.tokenStore.delete(token);
-  }
-
-  // ========================================================================
-  // UNIFIED AUTHENTICATION
-  // ========================================================================
-
-  /**
-   * Validate any token (NPM, Maven, OCI, PyPI, RubyGems, Composer, Cargo)
-   * @param tokenString - Token string (UUID or JWT)
-   * @param protocol - Expected protocol type
-   * @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)
-    if (this.isValidUuid(tokenString)) {
-      // Try NPM token
-      const npmToken = await this.validateNpmToken(tokenString);
-      if (npmToken && (!protocol || protocol === 'npm')) {
-        return npmToken;
-      }
-
-      // Try Maven token
-      const mavenToken = await this.validateMavenToken(tokenString);
-      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
-    const ociToken = await this.validateOciToken(tokenString);
-    if (ociToken && (!protocol || protocol === 'oci')) {
-      return ociToken;
-    }
-
-    return null;
-  }
-
-  /**
-   * Check if token has permission for an action
-   * @param token - Auth token
-   * @param resource - Resource being accessed (e.g., "package:foo" or "repository:bar")
-   * @param action - Action being performed (read, write, push, pull, delete)
-   * @returns true if authorized
-   */
-  public async authorize(
-    token: IAuthToken | null,
-    resource: string,
-    action: string
-  ): Promise<boolean> {
-    if (!token) {
-      return false;
-    }
-
-    // Check readonly flag
-    if (token.readonly && ['write', 'push', 'delete'].includes(action)) {
-      return false;
-    }
-
-    // Check scopes
-    for (const scope of token.scopes) {
-      if (this.matchesScope(scope, resource, action)) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  // ========================================================================
-  // HELPER METHODS
-  // ========================================================================
-
-  /**
-   * Check if a scope matches a resource and action
-   * Scope format: "{protocol}:{type}:{name}:{action}"
-   * Examples:
-   * - "npm:*:*" - All NPM access
-   * - "npm:package:foo:*" - All actions on package foo
-   * - "npm:package:foo:read" - Read-only on package foo
-   * - "oci:repository:*:pull" - Pull from any OCI repo
-   */
-  private matchesScope(scope: string, resource: string, action: string): boolean {
-    const scopeParts = scope.split(':');
-    const resourceParts = resource.split(':');
-
-    // Scope must have at least protocol:type:name:action
-    if (scopeParts.length < 4) {
-      return false;
-    }
-
-    const [scopeProtocol, scopeType, scopeName, scopeAction] = scopeParts;
-    const [resourceProtocol, resourceType, resourceName] = resourceParts;
-
-    // Check protocol
-    if (scopeProtocol !== '*' && scopeProtocol !== resourceProtocol) {
-      return false;
-    }
-
-    // Check type
-    if (scopeType !== '*' && scopeType !== resourceType) {
-      return false;
-    }
-
-    // Check name
-    if (scopeName !== '*' && scopeName !== resourceName) {
-      return false;
-    }
-
-    // Check action
-    if (scopeAction !== '*' && scopeAction !== action) {
-      // Map action aliases
-      const actionAliases: Record<string, string[]> = {
-        read: ['pull', 'get'],
-        write: ['push', 'put', 'post'],
-      };
-
-      const aliases = actionAliases[scopeAction] || [];
-      if (!aliases.includes(action)) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-
-  /**
-   * Convert unified scopes to OCI access array
-   */
-  private scopesToOciAccess(scopes: string[]): Array<{
-    type: string;
-    name: string;
-    actions: string[];
-  }> {
-    const access: Array<{type: string; name: string; actions: string[]}> = [];
-
-    for (const scope of scopes) {
-      const parts = scope.split(':');
-      if (parts.length >= 4 && parts[0] === 'oci') {
-        access.push({
-          type: parts[1],
-          name: parts[2],
-          actions: [parts[3]],
-        });
-      }
-    }
-
-    return access;
-  }
-
-  /**
-   * Convert OCI access array to unified scopes
-   */
-  private ociAccessToScopes(access: Array<{
-    type: string;
-    name: string;
-    actions: string[];
-  }>): string[] {
-    const scopes: string[] = [];
-
-    for (const item of access) {
-      for (const action of item.actions) {
-        scopes.push(`oci:${item.type}:${item.name}:${action}`);
-      }
-    }
-
-    return scopes;
-  }
-
-  /**
-   * Generate UUID for NPM tokens
-   */
-  private generateUuid(): string {
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-      const r = (Math.random() * 16) | 0;
-      const v = c === 'x' ? r : (r & 0x3) | 0x8;
-      return v.toString(16);
-    });
-  }
-
-  /**
-   * Check if string is a valid UUID
-   */
-  private isValidUuid(str: string): boolean {
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-    return uuidRegex.test(str);
-  }
-
-  /**
-   * Hash a token for identification (SHA-512 mock)
-   */
-  private hashToken(token: string): string {
-    // In production, use actual SHA-512
-    return `sha512-${token.substring(0, 16)}...`;
+    return this.provider.revokeToken(token);
   }
 }

ts/core/classes.defaultauthprovider.ts

@@ -0,0 +1,393 @@
+import * as crypto from 'crypto';
+import type { IAuthProvider, ITokenOptions } from './interfaces.auth.js';
+import type { IAuthConfig, IAuthToken, ICredentials, TRegistryProtocol } from './interfaces.core.js';
+
+/**
+ * Default in-memory authentication provider.
+ * This is the reference implementation that stores tokens in memory.
+ * For production use, implement IAuthProvider with Redis, database, or external auth.
+ */
+export class DefaultAuthProvider implements IAuthProvider {
+  private tokenStore: Map<string, IAuthToken> = new Map();
+  private userCredentials: Map<string, string> = new Map(); // username -> password hash (mock)
+
+  constructor(private config: IAuthConfig) {}
+
+  /**
+   * Initialize the auth provider
+   */
+  public async init(): Promise<void> {
+    // Initialize token store (in-memory for now)
+    // In production, this could be Redis or a database
+  }
+
+  // ========================================================================
+  // IAuthProvider Implementation
+  // ========================================================================
+
+  /**
+   * Authenticate user credentials
+   */
+  public async authenticate(credentials: ICredentials): Promise<string | null> {
+    // Mock authentication - in production, verify against database/LDAP
+    const storedPassword = this.userCredentials.get(credentials.username);
+
+    if (!storedPassword) {
+      // Auto-register for testing (remove in production)
+      this.userCredentials.set(credentials.username, credentials.password);
+      return credentials.username;
+    }
+
+    if (storedPassword === credentials.password) {
+      return credentials.username;
+    }
+
+    return null;
+  }
+
+  /**
+   * Validate any token (NPM, Maven, OCI, PyPI, RubyGems, Composer, Cargo)
+   */
+  public async validateToken(
+    tokenString: string,
+    protocol?: TRegistryProtocol
+  ): Promise<IAuthToken | null> {
+    // OCI uses JWT (contains dots), not UUID - check first if OCI is expected
+    if (protocol === 'oci' || tokenString.includes('.')) {
+      const ociToken = await this.validateOciToken(tokenString);
+      if (ociToken && (!protocol || protocol === 'oci')) {
+        return ociToken;
+      }
+      // If protocol was explicitly OCI but validation failed, return null
+      if (protocol === 'oci') {
+        return null;
+      }
+    }
+
+    // UUID-based tokens: single O(1) Map lookup
+    if (this.isValidUuid(tokenString)) {
+      const authToken = this.tokenStore.get(tokenString);
+      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;
+  }
+
+  /**
+   * Create a new token for a user
+   */
+  public async createToken(
+    userId: string,
+    protocol: TRegistryProtocol,
+    options?: ITokenOptions
+  ): Promise<string> {
+    // OCI tokens use JWT
+    if (protocol === 'oci') {
+      return this.createOciToken(userId, options?.scopes || ['oci:*:*:*'], options?.expiresIn || 3600);
+    }
+
+    // All other protocols use UUID tokens
+    const token = this.generateUuid();
+    const scopes = options?.scopes || (options?.readonly
+      ? [`${protocol}:*:*:read`]
+      : [`${protocol}:*:*:*`]);
+
+    const authToken: IAuthToken = {
+      type: protocol,
+      userId,
+      scopes,
+      readonly: options?.readonly,
+      expiresAt: options?.expiresIn ? new Date(Date.now() + options.expiresIn * 1000) : undefined,
+      metadata: {
+        created: new Date().toISOString(),
+      },
+    };
+
+    this.tokenStore.set(token, authToken);
+    return token;
+  }
+
+  /**
+   * Revoke a token
+   */
+  public async revokeToken(token: string): Promise<void> {
+    this.tokenStore.delete(token);
+  }
+
+  /**
+   * Check if token has permission for an action
+   */
+  public async authorize(
+    token: IAuthToken | null,
+    resource: string,
+    action: string
+  ): Promise<boolean> {
+    if (!token) {
+      return false;
+    }
+
+    // Check readonly flag
+    if (token.readonly && ['write', 'push', 'delete'].includes(action)) {
+      return false;
+    }
+
+    // Check scopes
+    for (const scope of token.scopes) {
+      if (this.matchesScope(scope, resource, action)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * List all tokens for a user
+   */
+  public async listUserTokens(userId: string): Promise<Array<{
+    key: string;
+    readonly: boolean;
+    created: string;
+    protocol?: TRegistryProtocol;
+  }>> {
+    const tokens: Array<{key: string; readonly: boolean; created: string; protocol?: TRegistryProtocol}> = [];
+
+    for (const [token, authToken] of this.tokenStore.entries()) {
+      if (authToken.userId === userId) {
+        tokens.push({
+          key: this.hashToken(token),
+          readonly: authToken.readonly || false,
+          created: authToken.metadata?.created || 'unknown',
+          protocol: authToken.type,
+        });
+      }
+    }
+
+    return tokens;
+  }
+
+  // ========================================================================
+  // OCI JWT Token Methods
+  // ========================================================================
+
+  /**
+   * Create an OCI JWT token
+   */
+  private async createOciToken(
+    userId: string,
+    scopes: string[],
+    expiresIn: number = 3600
+  ): Promise<string> {
+    if (!this.config.ociTokens?.enabled) {
+      throw new Error('OCI tokens are not enabled');
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    const payload = {
+      iss: this.config.ociTokens.realm,
+      sub: userId,
+      aud: this.config.ociTokens.service,
+      exp: now + expiresIn,
+      nbf: now,
+      iat: now,
+      access: this.scopesToOciAccess(scopes),
+    };
+
+    // Create JWT with HMAC-SHA256 signature
+    const header = { alg: 'HS256', typ: 'JWT' };
+    const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
+    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+
+    const signature = crypto
+      .createHmac('sha256', this.config.jwtSecret)
+      .update(`${headerB64}.${payloadB64}`)
+      .digest('base64url');
+
+    return `${headerB64}.${payloadB64}.${signature}`;
+  }
+
+  /**
+   * Validate an OCI JWT token
+   */
+  private async validateOciToken(jwt: string): Promise<IAuthToken | null> {
+    try {
+      const parts = jwt.split('.');
+      if (parts.length !== 3) {
+        return null;
+      }
+
+      const [headerB64, payloadB64, signatureB64] = parts;
+
+      // Verify signature
+      const expectedSignature = crypto
+        .createHmac('sha256', this.config.jwtSecret)
+        .update(`${headerB64}.${payloadB64}`)
+        .digest('base64url');
+
+      if (signatureB64 !== expectedSignature) {
+        return null;
+      }
+
+      // Decode and parse payload
+      const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf-8'));
+
+      // Check expiration
+      const now = Math.floor(Date.now() / 1000);
+      if (payload.exp && payload.exp < now) {
+        return null;
+      }
+
+      // Check not-before time
+      if (payload.nbf && payload.nbf > now) {
+        return null;
+      }
+
+      // Convert to unified token format
+      const scopes = this.ociAccessToScopes(payload.access || []);
+
+      return {
+        type: 'oci',
+        userId: payload.sub,
+        scopes,
+        expiresAt: payload.exp ? new Date(payload.exp * 1000) : undefined,
+        metadata: {
+          iss: payload.iss,
+          aud: payload.aud,
+        },
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  // ========================================================================
+  // Helper Methods
+  // ========================================================================
+
+  /**
+   * Check if a scope matches a resource and action
+   */
+  private matchesScope(scope: string, resource: string, action: string): boolean {
+    const scopeParts = scope.split(':');
+    const resourceParts = resource.split(':');
+
+    // Scope must have at least protocol:type:name:action
+    if (scopeParts.length < 4) {
+      return false;
+    }
+
+    const [scopeProtocol, scopeType, scopeName, scopeAction] = scopeParts;
+    const [resourceProtocol, resourceType, resourceName] = resourceParts;
+
+    // Check protocol
+    if (scopeProtocol !== '*' && scopeProtocol !== resourceProtocol) {
+      return false;
+    }
+
+    // Check type
+    if (scopeType !== '*' && scopeType !== resourceType) {
+      return false;
+    }
+
+    // Check name
+    if (scopeName !== '*' && scopeName !== resourceName) {
+      return false;
+    }
+
+    // Check action
+    if (scopeAction !== '*' && scopeAction !== action) {
+      // Map action aliases
+      const actionAliases: Record<string, string[]> = {
+        read: ['pull', 'get'],
+        write: ['push', 'put', 'post'],
+      };
+
+      const aliases = actionAliases[scopeAction] || [];
+      if (!aliases.includes(action)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Convert unified scopes to OCI access array
+   */
+  private scopesToOciAccess(scopes: string[]): Array<{
+    type: string;
+    name: string;
+    actions: string[];
+  }> {
+    const access: Array<{type: string; name: string; actions: string[]}> = [];
+
+    for (const scope of scopes) {
+      const parts = scope.split(':');
+      if (parts.length >= 4 && parts[0] === 'oci') {
+        access.push({
+          type: parts[1],
+          name: parts[2],
+          actions: [parts[3]],
+        });
+      }
+    }
+
+    return access;
+  }
+
+  /**
+   * Convert OCI access array to unified scopes
+   */
+  private ociAccessToScopes(access: Array<{
+    type: string;
+    name: string;
+    actions: string[];
+  }>): string[] {
+    const scopes: string[] = [];
+
+    for (const item of access) {
+      for (const action of item.actions) {
+        scopes.push(`oci:${item.type}:${item.name}:${action}`);
+      }
+    }
+
+    return scopes;
+  }
+
+  /**
+   * Generate UUID for tokens
+   */
+  private generateUuid(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = (Math.random() * 16) | 0;
+      const v = c === 'x' ? r : (r & 0x3) | 0x8;
+      return v.toString(16);
+    });
+  }
+
+  /**
+   * Check if string is a valid UUID
+   */
+  private isValidUuid(str: string): boolean {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(str);
+  }
+
+  /**
+   * Hash a token for identification
+   */
+  private hashToken(token: string): string {
+    return `sha512-${token.substring(0, 16)}...`;
+  }
+}

ts/core/classes.registrystorage.ts

@@ -1,17 +1,54 @@
 import * as plugins from '../plugins.js';
-import type { IStorageConfig, IStorageBackend } from './interfaces.core.js';
+import type { IStorageConfig, IStorageBackend, TRegistryProtocol } from './interfaces.core.js';
+import type {
+  IStorageHooks,
+  IStorageHookContext,
+  IStorageActor,
+  IStorageMetadata,
+} from './interfaces.storage.js';
 
 /**
- * Storage abstraction layer for registry
- * Provides a unified interface over SmartBucket
+ * Storage abstraction layer for registry.
+ * Provides a unified interface over SmartBucket with optional hooks
+ * for quota tracking, audit logging, cache invalidation, etc.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const storage = new RegistryStorage(config);
+ *
+ * // With hooks for quota tracking
+ * const storage = new RegistryStorage(config, {
+ *   beforePut: async (ctx) => {
+ *     const quota = await getQuota(ctx.actor?.orgId);
+ *     const usage = await getUsage(ctx.actor?.orgId);
+ *     if (usage + (ctx.metadata?.size || 0) > quota) {
+ *       return { allowed: false, reason: 'Quota exceeded' };
+ *     }
+ *     return { allowed: true };
+ *   },
+ *   afterPut: async (ctx) => {
+ *     await updateUsage(ctx.actor?.orgId, ctx.metadata?.size || 0);
+ *   }
+ * });
+ * ```
  */
 export class RegistryStorage implements IStorageBackend {
-  private smartBucket: plugins.smartbucket.SmartBucket;
-  private bucket: plugins.smartbucket.Bucket;
+  private smartBucket!: plugins.smartbucket.SmartBucket;
+  private bucket!: plugins.smartbucket.Bucket;
   private bucketName: string;
+  private hooks?: IStorageHooks;
 
-  constructor(private config: IStorageConfig) {
+  constructor(private config: IStorageConfig, hooks?: IStorageHooks) {
     this.bucketName = config.bucketName;
+    this.hooks = hooks;
+  }
+
+  /**
+   * Set storage hooks (can be called after construction)
+   */
+  public setHooks(hooks: IStorageHooks): void {
+    this.hooks = hooks;
   }
 
   /**
@@ -34,7 +71,24 @@ export class RegistryStorage implements IStorageBackend {
    */
   public async getObject(key: string): Promise<Buffer | null> {
     try {
-      return await this.bucket.fastGet({ path: key });
+      const data = await this.bucket.fastGet({ path: key });
+
+      // Call afterGet hook (non-blocking)
+      if (this.hooks?.afterGet && data) {
+        const context = this.currentContext;
+        if (context) {
+          this.hooks.afterGet({
+            operation: 'get',
+            key,
+            protocol: context.protocol,
+            actor: context.actor,
+            metadata: context.metadata,
+            timestamp: new Date(),
+          }).catch(() => {}); // Don't fail on hook errors
+        }
+      }
+
+      return data;
     } catch (error) {
       return null;
     }
@@ -48,19 +102,159 @@ export class RegistryStorage implements IStorageBackend {
     data: Buffer,
     metadata?: Record<string, string>
   ): Promise<void> {
+    // Call beforePut hook if available
+    if (this.hooks?.beforePut) {
+      const context = this.currentContext;
+      if (context) {
+        const hookContext: IStorageHookContext = {
+          operation: 'put',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: {
+            ...context.metadata,
+            size: data.length,
+          },
+          timestamp: new Date(),
+        };
+
+        const result = await this.hooks.beforePut(hookContext);
+        if (!result.allowed) {
+          throw new Error(result.reason || 'Storage operation denied by hook');
+        }
+      }
+    }
+
     // Note: SmartBucket doesn't support metadata yet
     await this.bucket.fastPut({
       path: key,
       contents: data,
       overwrite: true, // Always overwrite existing objects
     });
+
+    // Call afterPut hook (non-blocking)
+    if (this.hooks?.afterPut) {
+      const context = this.currentContext;
+      if (context) {
+        this.hooks.afterPut({
+          operation: 'put',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: {
+            ...context.metadata,
+            size: data.length,
+          },
+          timestamp: new Date(),
+        }).catch(() => {}); // Don't fail on hook errors
+      }
+    }
   }
 
   /**
    * Delete an object
    */
   public async deleteObject(key: string): Promise<void> {
+    // Call beforeDelete hook if available
+    if (this.hooks?.beforeDelete) {
+      const context = this.currentContext;
+      if (context) {
+        const hookContext: IStorageHookContext = {
+          operation: 'delete',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: context.metadata,
+          timestamp: new Date(),
+        };
+
+        const result = await this.hooks.beforeDelete(hookContext);
+        if (!result.allowed) {
+          throw new Error(result.reason || 'Delete operation denied by hook');
+        }
+      }
+    }
+
     await this.bucket.fastRemove({ path: key });
+
+    // Call afterDelete hook (non-blocking)
+    if (this.hooks?.afterDelete) {
+      const context = this.currentContext;
+      if (context) {
+        this.hooks.afterDelete({
+          operation: 'delete',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: context.metadata,
+          timestamp: new Date(),
+        }).catch(() => {}); // Don't fail on hook errors
+      }
+    }
+  }
+
+  // ========================================================================
+  // CONTEXT FOR HOOKS
+  // ========================================================================
+
+  /**
+   * Current operation context for hooks.
+   * Set this before performing storage operations to enable hooks.
+   */
+  private currentContext?: {
+    protocol: TRegistryProtocol;
+    actor?: IStorageActor;
+    metadata?: IStorageMetadata;
+  };
+
+  /**
+   * Set the current operation context for hooks.
+   * Call this before performing storage operations.
+   *
+   * @example
+   * ```typescript
+   * storage.setContext({
+   *   protocol: 'npm',
+   *   actor: { userId: 'user123', ip: '192.168.1.1' },
+   *   metadata: { packageName: 'lodash', version: '4.17.21' }
+   * });
+   * await storage.putNpmTarball('lodash', '4.17.21', tarball);
+   * storage.clearContext();
+   * ```
+   */
+  public setContext(context: {
+    protocol: TRegistryProtocol;
+    actor?: IStorageActor;
+    metadata?: IStorageMetadata;
+  }): void {
+    this.currentContext = context;
+  }
+
+  /**
+   * Clear the current operation context.
+   */
+  public clearContext(): void {
+    this.currentContext = undefined;
+  }
+
+  /**
+   * Execute a function with a temporary context.
+   * Context is automatically cleared after execution.
+   */
+  public async withContext<T>(
+    context: {
+      protocol: TRegistryProtocol;
+      actor?: IStorageActor;
+      metadata?: IStorageMetadata;
+    },
+    fn: () => Promise<T>
+  ): Promise<T> {
+    this.setContext(context);
+    try {
+      return await fn();
+    } finally {
+      this.clearContext();
+    }
   }
 
   /**
@@ -1072,4 +1266,135 @@ export class RegistryStorage implements IStorageBackend {
   private getRubyGemsMetadataPath(gemName: string): string {
     return `rubygems/metadata/${gemName}/metadata.json`;
   }
+
+  // ========================================================================
+  // STREAMING METHODS (Web Streams API)
+  // ========================================================================
+
+  /**
+   * Get an object as a ReadableStream. Returns null if not found.
+   */
+  public async getObjectStream(key: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    try {
+      const stat = await this.bucket.fastStat({ path: key });
+      const size = stat.ContentLength ?? 0;
+      const stream = await this.bucket.fastGetStream({ path: key }, 'webstream');
+
+      // Call afterGet hook (non-blocking)
+      if (this.hooks?.afterGet) {
+        const context = this.currentContext;
+        if (context) {
+          this.hooks.afterGet({
+            operation: 'get',
+            key,
+            protocol: context.protocol,
+            actor: context.actor,
+            metadata: context.metadata,
+            timestamp: new Date(),
+          }).catch(() => {});
+        }
+      }
+
+      return { stream: stream as ReadableStream<Uint8Array>, size };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Store an object from a ReadableStream.
+   */
+  public async putObjectStream(key: string, stream: ReadableStream<Uint8Array>): Promise<void> {
+    if (this.hooks?.beforePut) {
+      const context = this.currentContext;
+      if (context) {
+        const hookContext: IStorageHookContext = {
+          operation: 'put',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: context.metadata,
+          timestamp: new Date(),
+        };
+        const result = await this.hooks.beforePut(hookContext);
+        if (!result.allowed) {
+          throw new Error(result.reason || 'Storage operation denied by hook');
+        }
+      }
+    }
+
+    // Convert WebStream to Node Readable at the S3 SDK boundary
+    // AWS SDK v3 PutObjectCommand requires a Node.js Readable (not WebStream)
+    const { Readable } = await import('stream');
+    const nodeStream = Readable.fromWeb(stream as any);
+    await this.bucket.fastPutStream({
+      path: key,
+      readableStream: nodeStream,
+      overwrite: true,
+    });
+
+    if (this.hooks?.afterPut) {
+      const context = this.currentContext;
+      if (context) {
+        this.hooks.afterPut({
+          operation: 'put',
+          key,
+          protocol: context.protocol,
+          actor: context.actor,
+          metadata: context.metadata,
+          timestamp: new Date(),
+        }).catch(() => {});
+      }
+    }
+  }
+
+  /**
+   * Get object size without reading data (S3 HEAD request).
+   */
+  public async getObjectSize(key: string): Promise<number | null> {
+    try {
+      const stat = await this.bucket.fastStat({ path: key });
+      return stat.ContentLength ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  // ---- Protocol-specific streaming wrappers ----
+
+  public async getOciBlobStream(digest: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getOciBlobPath(digest));
+  }
+
+  public async putOciBlobStream(digest: string, stream: ReadableStream<Uint8Array>): Promise<void> {
+    return this.putObjectStream(this.getOciBlobPath(digest), stream);
+  }
+
+  public async getOciBlobSize(digest: string): Promise<number | null> {
+    return this.getObjectSize(this.getOciBlobPath(digest));
+  }
+
+  public async getNpmTarballStream(packageName: string, version: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getNpmTarballPath(packageName, version));
+  }
+
+  public async getMavenArtifactStream(groupId: string, artifactId: string, version: string, filename: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getMavenArtifactPath(groupId, artifactId, version, filename));
+  }
+
+  public async getCargoCrateStream(crateName: string, version: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getCargoCratePath(crateName, version));
+  }
+
+  public async getComposerPackageZipStream(vendorPackage: string, reference: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getComposerZipPath(vendorPackage, reference));
+  }
+
+  public async getPypiPackageFileStream(packageName: string, filename: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getPypiPackageFilePath(packageName, filename));
+  }
+
+  public async getRubyGemsGemStream(gemName: string, version: string, platform?: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null> {
+    return this.getObjectStream(this.getRubyGemsGemPath(gemName, version, platform));
+  }
 }

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/core/helpers.stream.ts

@@ -0,0 +1,63 @@
+import * as crypto from 'crypto';
+
+/**
+ * Convert Buffer, Uint8Array, string, or JSON object to a ReadableStream<Uint8Array>.
+ */
+export function toReadableStream(data: Buffer | Uint8Array | string | object): ReadableStream<Uint8Array> {
+  const buf = Buffer.isBuffer(data)
+    ? data
+    : data instanceof Uint8Array
+      ? Buffer.from(data)
+      : typeof data === 'string'
+        ? Buffer.from(data, 'utf-8')
+        : Buffer.from(JSON.stringify(data), 'utf-8');
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new Uint8Array(buf));
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Consume a ReadableStream into a Buffer.
+ */
+export async function streamToBuffer(stream: ReadableStream<Uint8Array>): Promise<Buffer> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Consume a ReadableStream into a parsed JSON object.
+ */
+export async function streamToJson<T = any>(stream: ReadableStream<Uint8Array>): Promise<T> {
+  const buf = await streamToBuffer(stream);
+  return JSON.parse(buf.toString('utf-8'));
+}
+
+/**
+ * Create a TransformStream that incrementally hashes data passing through.
+ * Data flows through unchanged; the digest is available after the stream completes.
+ */
+export function createHashTransform(algorithm: string = 'sha256'): {
+  transform: TransformStream<Uint8Array, Uint8Array>;
+  getDigest: () => string;
+} {
+  const hash = crypto.createHash(algorithm);
+  const transform = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      hash.update(chunk);
+      controller.enqueue(chunk);
+    },
+  });
+  return {
+    transform,
+    getDigest: () => hash.digest('hex'),
+  };
+}

ts/core/index.ts

@@ -2,9 +2,19 @@
  * Core registry infrastructure exports
  */
 
-// Interfaces
+// Core interfaces
 export * from './interfaces.core.js';
 
+// Auth interfaces and provider
+export * from './interfaces.auth.js';
+export { DefaultAuthProvider } from './classes.defaultauthprovider.js';
+
+// Storage interfaces and hooks
+export * from './interfaces.storage.js';
+
+// Stream helpers
+export { toReadableStream, streamToBuffer, streamToJson, createHashTransform } from './helpers.stream.js';
+
 // Classes
 export { BaseRegistry } from './classes.baseregistry.js';
 export { RegistryStorage } from './classes.registrystorage.js';

ts/core/interfaces.auth.ts

@@ -0,0 +1,91 @@
+import type { IAuthToken, ICredentials, TRegistryProtocol } from './interfaces.core.js';
+
+/**
+ * Options for creating a token
+ */
+export interface ITokenOptions {
+  /** Whether the token is readonly */
+  readonly?: boolean;
+  /** Permission scopes */
+  scopes?: string[];
+  /** Expiration time in seconds */
+  expiresIn?: number;
+}
+
+/**
+ * Pluggable authentication provider interface.
+ * Implement this to integrate external auth systems (LDAP, OAuth, SSO, OIDC).
+ *
+ * @example
+ * ```typescript
+ * class LdapAuthProvider implements IAuthProvider {
+ *   constructor(private ldap: LdapClient, private redis: RedisClient) {}
+ *
+ *   async authenticate(credentials: ICredentials): Promise<string | null> {
+ *     return await this.ldap.bind(credentials.username, credentials.password);
+ *   }
+ *
+ *   async validateToken(token: string): Promise<IAuthToken | null> {
+ *     return await this.redis.get(`token:${token}`);
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface IAuthProvider {
+  /**
+   * Initialize the auth provider (optional)
+   */
+  init?(): Promise<void>;
+
+  /**
+   * Authenticate user credentials (login flow)
+   * @param credentials - Username and password
+   * @returns User ID on success, null on failure
+   */
+  authenticate(credentials: ICredentials): Promise<string | null>;
+
+  /**
+   * Validate an existing token
+   * @param token - Token string (UUID or JWT)
+   * @param protocol - Optional protocol hint for optimization
+   * @returns Auth token info or null if invalid
+   */
+  validateToken(token: string, protocol?: TRegistryProtocol): Promise<IAuthToken | null>;
+
+  /**
+   * Create a new token for a user
+   * @param userId - User ID
+   * @param protocol - Protocol type (npm, oci, maven, etc.)
+   * @param options - Token options (readonly, scopes, expiration)
+   * @returns Token string
+   */
+  createToken(userId: string, protocol: TRegistryProtocol, options?: ITokenOptions): Promise<string>;
+
+  /**
+   * Revoke a token
+   * @param token - Token string to revoke
+   */
+  revokeToken(token: string): Promise<void>;
+
+  /**
+   * Check if user has permission for an action
+   * @param token - Auth token (or null for anonymous)
+   * @param resource - Resource being accessed (e.g., "npm:package:lodash")
+   * @param action - Action being performed (read, write, push, pull, delete)
+   * @returns true if authorized
+   */
+  authorize(token: IAuthToken | null, resource: string, action: string): Promise<boolean>;
+
+  /**
+   * List all tokens for a user (optional)
+   * @param userId - User ID
+   * @returns List of token info
+   */
+  listUserTokens?(userId: string): Promise<Array<{
+    key: string;
+    readonly: boolean;
+    created: string;
+    protocol?: TRegistryProtocol;
+  }>>;
+}

ts/core/interfaces.core.ts

@@ -3,6 +3,9 @@
  */
 
 import type * as plugins from '../plugins.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import type { IAuthProvider } from './interfaces.auth.js';
+import type { IStorageHooks } from './interfaces.storage.js';
 
 /**
  * Registry protocol types
@@ -85,6 +88,7 @@ export interface IAuthConfig {
 export interface IProtocolConfig {
   enabled: boolean;
   basePath: string;
+  registryUrl?: string;
   features?: Record<string, boolean>;
 }
 
@@ -94,6 +98,27 @@ export interface IProtocolConfig {
 export interface IRegistryConfig {
   storage: IStorageConfig;
   auth: IAuthConfig;
+
+  /**
+   * Custom authentication provider.
+   * If not provided, uses the default in-memory auth provider.
+   * Implement IAuthProvider to integrate LDAP, OAuth, SSO, etc.
+   */
+  authProvider?: IAuthProvider;
+
+  /**
+   * Storage event hooks for quota tracking, audit logging, etc.
+   * Called before/after storage operations.
+   */
+  storageHooks?: IStorageHooks;
+
+  /**
+   * Dynamic upstream configuration provider.
+   * Called per-request to resolve which upstream registries to use.
+   * Use StaticUpstreamProvider for simple static configurations.
+   */
+  upstreamProvider?: IUpstreamProvider;
+
   oci?: IProtocolConfig;
   npm?: IProtocolConfig;
   maven?: IProtocolConfig;
@@ -136,6 +161,21 @@ export interface IStorageBackend {
    * Get object metadata
    */
   getMetadata(key: string): Promise<Record<string, string> | null>;
+
+  /**
+   * Get an object as a ReadableStream. Returns null if not found.
+   */
+  getObjectStream?(key: string): Promise<{ stream: ReadableStream<Uint8Array>; size: number } | null>;
+
+  /**
+   * Store an object from a ReadableStream.
+   */
+  putObjectStream?(key: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+
+  /**
+   * Get object size without reading data (S3 HEAD request).
+   */
+  getObjectSize?(key: string): Promise<number | null>;
 }
 
 /**
@@ -149,6 +189,24 @@ export interface IRegistryError {
   }>;
 }
 
+/**
+ * Actor information - identifies who is performing the request
+ */
+export interface IRequestActor {
+  /** User ID (from validated token) */
+  userId?: string;
+  /** Token ID/hash for audit purposes */
+  tokenId?: string;
+  /** Client IP address */
+  ip?: string;
+  /** Client User-Agent */
+  userAgent?: string;
+  /** Organization ID (for multi-tenant setups) */
+  orgId?: string;
+  /** Session ID */
+  sessionId?: string;
+}
+
 /**
  * Base request context
  */
@@ -165,13 +223,21 @@ export interface IRequestContext {
    */
   rawBody?: Buffer;
   token?: string;
+  /**
+   * Actor information - identifies who is performing the request.
+   * Populated after authentication for audit logging, quota enforcement, etc.
+   */
+  actor?: IRequestActor;
 }
 
 /**
- * Base response structure
+ * Base response structure.
+ * `body` is always a `ReadableStream<Uint8Array>` at the public API boundary.
+ * Internal handlers may return Buffer/string/object — the SmartRegistry orchestrator
+ * auto-wraps them via `toReadableStream()` before returning to the caller.
  */
 export interface IResponse {
   status: number;
   headers: Record<string, string>;
-  body?: any;
+  body?: ReadableStream<Uint8Array> | any;
 }

ts/core/interfaces.storage.ts

@@ -0,0 +1,130 @@
+import type { TRegistryProtocol } from './interfaces.core.js';
+
+/**
+ * Actor information from request context
+ */
+export interface IStorageActor {
+  userId?: string;
+  tokenId?: string;
+  ip?: string;
+  userAgent?: string;
+  orgId?: string;
+  sessionId?: string;
+}
+
+/**
+ * Metadata about the storage operation
+ */
+export interface IStorageMetadata {
+  /** Content type of the object */
+  contentType?: string;
+  /** Size in bytes */
+  size?: number;
+  /** Content digest (e.g., sha256:abc123) */
+  digest?: string;
+  /** Package/artifact name */
+  packageName?: string;
+  /** Version */
+  version?: string;
+}
+
+/**
+ * Context passed to storage hooks
+ */
+export interface IStorageHookContext {
+  /** Type of operation */
+  operation: 'put' | 'delete' | 'get';
+  /** Storage key/path */
+  key: string;
+  /** Protocol that triggered this operation */
+  protocol: TRegistryProtocol;
+  /** Actor who performed the operation (if known) */
+  actor?: IStorageActor;
+  /** Metadata about the object */
+  metadata?: IStorageMetadata;
+  /** Timestamp of the operation */
+  timestamp: Date;
+}
+
+/**
+ * Result from a beforePut hook that can modify the operation
+ */
+export interface IBeforePutResult {
+  /** Whether to allow the operation */
+  allowed: boolean;
+  /** Optional reason for rejection */
+  reason?: string;
+  /** Optional modified metadata */
+  metadata?: IStorageMetadata;
+}
+
+/**
+ * Result from a beforeDelete hook
+ */
+export interface IBeforeDeleteResult {
+  /** Whether to allow the operation */
+  allowed: boolean;
+  /** Optional reason for rejection */
+  reason?: string;
+}
+
+/**
+ * Storage event hooks for quota tracking, audit logging, cache invalidation, etc.
+ *
+ * @example
+ * ```typescript
+ * const quotaHooks: IStorageHooks = {
+ *   async beforePut(context) {
+ *     const quota = await getQuota(context.actor?.orgId);
+ *     const currentUsage = await getUsage(context.actor?.orgId);
+ *     if (currentUsage + (context.metadata?.size || 0) > quota) {
+ *       return { allowed: false, reason: 'Quota exceeded' };
+ *     }
+ *     return { allowed: true };
+ *   },
+ *
+ *   async afterPut(context) {
+ *     await updateUsage(context.actor?.orgId, context.metadata?.size || 0);
+ *     await auditLog('storage.put', context);
+ *   },
+ *
+ *   async afterDelete(context) {
+ *     await invalidateCache(context.key);
+ *   }
+ * };
+ * ```
+ */
+export interface IStorageHooks {
+  /**
+   * Called before storing an object.
+   * Return { allowed: false } to reject the operation.
+   * Use for quota checks, virus scanning, validation, etc.
+   */
+  beforePut?(context: IStorageHookContext): Promise<IBeforePutResult>;
+
+  /**
+   * Called after successfully storing an object.
+   * Use for quota tracking, audit logging, notifications, etc.
+   */
+  afterPut?(context: IStorageHookContext): Promise<void>;
+
+  /**
+   * Called before deleting an object.
+   * Return { allowed: false } to reject the operation.
+   * Use for preventing deletion of protected resources.
+   */
+  beforeDelete?(context: IStorageHookContext): Promise<IBeforeDeleteResult>;
+
+  /**
+   * Called after successfully deleting an object.
+   * Use for quota updates, audit logging, cache invalidation, etc.
+   */
+  afterDelete?(context: IStorageHookContext): Promise<void>;
+
+  /**
+   * Called after reading an object.
+   * Use for access logging, analytics, etc.
+   * Note: This is called even for cache hits.
+   */
+  afterGet?(context: IStorageHookContext): Promise<void>;
+}

ts/index.ts

@@ -9,6 +9,9 @@ export { SmartRegistry } from './classes.smartregistry.js';
 // Core infrastructure
 export * from './core/index.js';
 
+// Upstream infrastructure
+export * from './upstream/index.js';
+
 // OCI Registry
 export * from './oci/index.js';
 

ts/maven/classes.mavenregistry.ts

@@ -6,7 +6,9 @@
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import { toBuffer } from '../core/helpers.buffer.js';
 import type { IMavenCoordinate, IMavenMetadata, IChecksums } from './interfaces.maven.js';
 import {
   pathToGAV,
@@ -20,6 +22,7 @@ import {
   extractGAVFromPom,
   gavToPath,
 } from './helpers.maven.js';
+import { MavenUpstream } from './classes.mavenupstream.js';
 
 /**
  * Maven Registry class
@@ -30,18 +33,64 @@ export class MavenRegistry extends BaseRegistry {
   private authManager: AuthManager;
   private basePath: string = '/maven';
   private registryUrl: string;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string,
-    registryUrl: string
+    registryUrl: string,
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
+  }
+
+  /**
+   * Extract scope from Maven coordinates.
+   * For Maven, the groupId is the scope.
+   * @example "com.example" from "com.example:my-lib"
+   */
+  private extractScope(groupId: string): string | null {
+    return groupId || null;
+  }
+
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<MavenUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    // For Maven, resource is "groupId:artifactId"
+    const [groupId] = resource.split(':');
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'maven',
+      resource,
+      scope: this.extractScope(groupId),
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new MavenUpstream(config);
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    // No persistent upstream to clean up with dynamic provider
   }
 
   public async init(): Promise<void> {
@@ -66,13 +115,21 @@ export class MavenRegistry extends BaseRegistry {
       token = await this.authManager.validateToken(tokenString, 'maven');
     }
 
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     // Parse path to determine request type
     const coordinate = pathToGAV(path);
 
     if (!coordinate) {
       // Not a valid artifact path, could be metadata or root
       if (path.endsWith('/maven-metadata.xml')) {
-        return this.handleMetadataRequest(context.method, path, token);
+        return this.handleMetadataRequest(context.method, path, token, actor);
       }
 
       return {
@@ -89,7 +146,7 @@ export class MavenRegistry extends BaseRegistry {
     }
 
     // Handle artifact requests (JAR, POM, WAR, etc.)
-    return this.handleArtifactRequest(context.method, coordinate, token, context.body);
+    return this.handleArtifactRequest(context.method, coordinate, token, context.body, actor);
   }
 
   protected async checkPermission(
@@ -109,7 +166,8 @@ export class MavenRegistry extends BaseRegistry {
     method: string,
     coordinate: IMavenCoordinate,
     token: IAuthToken | null,
-    body?: Buffer | any
+    body?: Buffer | any,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     const { groupId, artifactId, version } = coordinate;
     const filename = buildFilename(coordinate);
@@ -120,7 +178,7 @@ export class MavenRegistry extends BaseRegistry {
       case 'HEAD':
         // Maven repositories typically allow anonymous reads
         return method === 'GET'
-          ? this.getArtifact(groupId, artifactId, version, filename)
+          ? this.getArtifact(groupId, artifactId, version, filename, actor)
           : this.headArtifact(groupId, artifactId, version, filename);
 
       case 'PUT':
@@ -192,7 +250,8 @@ export class MavenRegistry extends BaseRegistry {
   private async handleMetadataRequest(
     method: string,
     path: string,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     // Parse path to extract groupId and artifactId
     // Path format: /com/example/my-lib/maven-metadata.xml
@@ -213,7 +272,7 @@ export class MavenRegistry extends BaseRegistry {
     if (method === 'GET') {
       // Metadata is usually public (read permission optional)
       // Some registries allow anonymous metadata access
-      return this.getMetadata(groupId, artifactId);
+      return this.getMetadata(groupId, artifactId, actor);
     }
 
     return {
@@ -231,9 +290,42 @@ export class MavenRegistry extends BaseRegistry {
     groupId: string,
     artifactId: string,
     version: string,
-    filename: string
+    filename: string,
+    actor?: IRequestActor
   ): Promise<IResponse> {
-    const data = await this.storage.getMavenArtifact(groupId, artifactId, version, filename);
+    // Try local storage first (streaming)
+    const streamResult = await this.storage.getMavenArtifactStream(groupId, artifactId, version, filename);
+    if (streamResult) {
+      const ext = filename.split('.').pop() || '';
+      const contentType = this.getContentType(ext);
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': contentType,
+          'Content-Length': streamResult.size.toString(),
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // Try upstream if not found locally
+    let data: Buffer | null = null;
+    const resource = `${groupId}:${artifactId}`;
+    const upstream = await this.getUpstreamForRequest(resource, 'artifact', 'GET', actor);
+    if (upstream) {
+      // Parse the filename to extract extension and classifier
+      const { extension, classifier } = this.parseFilename(filename, artifactId, version);
+      if (extension) {
+        data = await upstream.fetchArtifact(groupId, artifactId, version, extension, classifier);
+        if (data) {
+          // Cache the artifact locally
+          await this.storage.putMavenArtifact(groupId, artifactId, version, filename, data);
+          // Generate and store checksums
+          const checksums = await calculateChecksums(data);
+          await this.storeChecksums(groupId, artifactId, version, filename, checksums);
+        }
+      }
+    }
 
     if (!data) {
       return {
@@ -296,7 +388,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') {
@@ -460,8 +552,22 @@ export class MavenRegistry extends BaseRegistry {
   // METADATA OPERATIONS
   // ========================================================================
 
-  private async getMetadata(groupId: string, artifactId: string): Promise<IResponse> {
-    const metadataBuffer = await this.storage.getMavenMetadata(groupId, artifactId);
+  private async getMetadata(groupId: string, artifactId: string, actor?: IRequestActor): Promise<IResponse> {
+    let metadataBuffer = await this.storage.getMavenMetadata(groupId, artifactId);
+
+    // Try upstream if not found locally
+    if (!metadataBuffer) {
+      const resource = `${groupId}:${artifactId}`;
+      const upstream = await this.getUpstreamForRequest(resource, 'metadata', 'GET', actor);
+      if (upstream) {
+        const upstreamMetadata = await upstream.fetchMetadata(groupId, artifactId);
+        if (upstreamMetadata) {
+          metadataBuffer = Buffer.from(upstreamMetadata, 'utf-8');
+          // Cache the metadata locally
+          await this.storage.putMavenMetadata(groupId, artifactId, metadataBuffer);
+        }
+      }
+    }
 
     if (!metadataBuffer) {
       // Generate empty metadata if none exists
@@ -577,4 +683,41 @@ export class MavenRegistry extends BaseRegistry {
 
     return contentTypes[extension] || 'application/octet-stream';
   }
+
+  /**
+   * Parse a Maven filename to extract extension and classifier.
+   * Filename format: {artifactId}-{version}[-{classifier}].{extension}
+   */
+  private parseFilename(
+    filename: string,
+    artifactId: string,
+    version: string
+  ): { extension: string; classifier?: string } {
+    const prefix = `${artifactId}-${version}`;
+
+    if (!filename.startsWith(prefix)) {
+      // Fallback: just get the extension
+      const lastDot = filename.lastIndexOf('.');
+      return { extension: lastDot > 0 ? filename.slice(lastDot + 1) : '' };
+    }
+
+    const remainder = filename.slice(prefix.length);
+    // remainder is either ".extension" or "-classifier.extension"
+
+    if (remainder.startsWith('.')) {
+      return { extension: remainder.slice(1) };
+    }
+
+    if (remainder.startsWith('-')) {
+      const lastDot = remainder.lastIndexOf('.');
+      if (lastDot > 1) {
+        return {
+          classifier: remainder.slice(1, lastDot),
+          extension: remainder.slice(lastDot + 1),
+        };
+      }
+    }
+
+    return { extension: '' };
+  }
 }

ts/maven/classes.mavenupstream.ts

@@ -0,0 +1,220 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+import type { IMavenCoordinate } from './interfaces.maven.js';
+
+/**
+ * Maven-specific upstream implementation.
+ *
+ * Handles:
+ * - Artifact fetching (JAR, POM, WAR, etc.)
+ * - Metadata fetching (maven-metadata.xml)
+ * - Checksum files (.md5, .sha1, .sha256, .sha512)
+ * - SNAPSHOT version handling
+ * - Content-addressable caching for release artifacts
+ */
+export class MavenUpstream extends BaseUpstream {
+  protected readonly protocolName = 'maven';
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+  }
+
+  /**
+   * Fetch an artifact from upstream registries.
+   */
+  public async fetchArtifact(
+    groupId: string,
+    artifactId: string,
+    version: string,
+    extension: string,
+    classifier?: string,
+  ): Promise<Buffer | null> {
+    const path = this.buildArtifactPath(groupId, artifactId, version, extension, classifier);
+    const resource = `${groupId}:${artifactId}`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'maven',
+      resource,
+      resourceType: 'artifact',
+      path,
+      method: 'GET',
+      headers: {},
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Fetch maven-metadata.xml from upstream.
+   */
+  public async fetchMetadata(groupId: string, artifactId: string, version?: string): Promise<string | null> {
+    const groupPath = groupId.replace(/\./g, '/');
+    let path: string;
+
+    if (version) {
+      // Version-level metadata (for SNAPSHOTs)
+      path = `/${groupPath}/${artifactId}/${version}/maven-metadata.xml`;
+    } else {
+      // Artifact-level metadata (lists all versions)
+      path = `/${groupPath}/${artifactId}/maven-metadata.xml`;
+    }
+
+    const resource = `${groupId}:${artifactId}`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'maven',
+      resource,
+      resourceType: 'metadata',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/xml, text/xml',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch a checksum file from upstream.
+   */
+  public async fetchChecksum(
+    groupId: string,
+    artifactId: string,
+    version: string,
+    extension: string,
+    checksumType: 'md5' | 'sha1' | 'sha256' | 'sha512',
+    classifier?: string,
+  ): Promise<string | null> {
+    const basePath = this.buildArtifactPath(groupId, artifactId, version, extension, classifier);
+    const path = `${basePath}.${checksumType}`;
+    const resource = `${groupId}:${artifactId}`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'maven',
+      resource,
+      resourceType: 'checksum',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'text/plain',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8').trim();
+    }
+
+    return typeof result.body === 'string' ? result.body.trim() : null;
+  }
+
+  /**
+   * Check if an artifact exists in upstream (HEAD request).
+   */
+  public async headArtifact(
+    groupId: string,
+    artifactId: string,
+    version: string,
+    extension: string,
+    classifier?: string,
+  ): Promise<{ exists: boolean; size?: number; lastModified?: string } | null> {
+    const path = this.buildArtifactPath(groupId, artifactId, version, extension, classifier);
+    const resource = `${groupId}:${artifactId}`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'maven',
+      resource,
+      resourceType: 'artifact',
+      path,
+      method: 'HEAD',
+      headers: {},
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result) {
+      return null;
+    }
+
+    if (!result.success) {
+      return { exists: false };
+    }
+
+    return {
+      exists: true,
+      size: result.headers['content-length'] ? parseInt(result.headers['content-length'], 10) : undefined,
+      lastModified: result.headers['last-modified'],
+    };
+  }
+
+  /**
+   * Build the path for a Maven artifact.
+   */
+  private buildArtifactPath(
+    groupId: string,
+    artifactId: string,
+    version: string,
+    extension: string,
+    classifier?: string,
+  ): string {
+    const groupPath = groupId.replace(/\./g, '/');
+    let filename = `${artifactId}-${version}`;
+    if (classifier) {
+      filename += `-${classifier}`;
+    }
+    filename += `.${extension}`;
+
+    return `/${groupPath}/${artifactId}/${version}/${filename}`;
+  }
+
+  /**
+   * Override URL building for Maven-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/maven/index.ts

@@ -3,5 +3,6 @@
  */
 
 export { MavenRegistry } from './classes.mavenregistry.js';
+export { MavenUpstream } from './classes.mavenupstream.js';
 export * from './interfaces.maven.js';
 export * from './helpers.maven.js';

ts/npm/classes.npmregistry.ts

@@ -2,7 +2,9 @@ import { Smartlog } from '@push.rocks/smartlog';
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import { NpmUpstream } from './classes.npmupstream.js';
 import type {
   IPackument,
   INpmVersion,
@@ -25,18 +27,21 @@ export class NpmRegistry extends BaseRegistry {
   private basePath: string = '/npm';
   private registryUrl: string;
   private logger: Smartlog;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/npm',
-    registryUrl: string = 'http://localhost:5000/npm'
+    registryUrl: string = 'http://localhost:5000/npm',
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
 
     // Initialize logger
     this.logger = new Smartlog({
@@ -50,6 +55,50 @@ export class NpmRegistry extends BaseRegistry {
       }
     });
     this.logger.enableConsole();
+
+    if (upstreamProvider) {
+      this.logger.log('info', 'NPM upstream provider configured');
+    }
+  }
+
+  /**
+   * Extract scope from npm package name.
+   * @example "@company/utils" -> "company"
+   * @example "lodash" -> null
+   */
+  private extractScope(packageName: string): string | null {
+    if (packageName.startsWith('@')) {
+      const slashIndex = packageName.indexOf('/');
+      if (slashIndex > 1) {
+        return packageName.substring(1, slashIndex);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<NpmUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'npm',
+      resource,
+      scope: this.extractScope(resource),
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new NpmUpstream(config, this.registryUrl, this.logger);
   }
 
   public async init(): Promise<void> {
@@ -68,6 +117,14 @@ export class NpmRegistry extends BaseRegistry {
     const tokenString = authHeader?.replace(/^Bearer\s+/i, '');
     const token = tokenString ? await this.authManager.validateToken(tokenString, 'npm') : null;
 
+    // Build actor context for upstream resolution
+    const actor: IRequestActor = {
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['x-real-ip'],
+      userAgent: context.headers['user-agent'],
+      ...context.actor, // Include any pre-populated actor info
+    };
+
     this.logger.log('debug', `handleRequest: ${context.method} ${path}`, {
       method: context.method,
       path,
@@ -98,47 +155,47 @@ export class NpmRegistry extends BaseRegistry {
     // Dist-tags: /-/package/{package}/dist-tags
     const distTagsMatch = path.match(/^\/-\/package\/(@?[^\/]+(?:\/[^\/]+)?)\/dist-tags(?:\/(.+))?$/);
     if (distTagsMatch) {
-      const [, packageName, tag] = distTagsMatch;
-      return this.handleDistTags(context.method, packageName, tag, context.body, token);
+      const [, rawPkgName, tag] = distTagsMatch;
+      return this.handleDistTags(context.method, decodeURIComponent(rawPkgName), tag, context.body, token);
     }
 
     // Tarball download: /{package}/-/{filename}.tgz
     const tarballMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/-\/(.+\.tgz)$/);
     if (tarballMatch) {
-      const [, packageName, filename] = tarballMatch;
-      return this.handleTarballDownload(packageName, filename, token);
+      const [, rawPkgName, filename] = tarballMatch;
+      return this.handleTarballDownload(decodeURIComponent(rawPkgName), filename, token, actor);
     }
 
     // Unpublish specific version: DELETE /{package}/-/{version}
     const unpublishVersionMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/-\/([^\/]+)$/);
     if (unpublishVersionMatch && context.method === 'DELETE') {
-      const [, packageName, version] = unpublishVersionMatch;
-      console.log(`[unpublishVersionMatch] packageName=${packageName}, version=${version}`);
-      return this.unpublishVersion(packageName, version, token);
+      const [, rawPkgName, version] = unpublishVersionMatch;
+      this.logger.log('debug', 'unpublishVersionMatch', { packageName: decodeURIComponent(rawPkgName), version });
+      return this.unpublishVersion(decodeURIComponent(rawPkgName), version, token);
     }
 
     // Unpublish entire package: DELETE /{package}/-rev/{rev}
     const unpublishPackageMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/-rev\/([^\/]+)$/);
     if (unpublishPackageMatch && context.method === 'DELETE') {
-      const [, packageName, rev] = unpublishPackageMatch;
-      console.log(`[unpublishPackageMatch] packageName=${packageName}, rev=${rev}`);
-      return this.unpublishPackage(packageName, token);
+      const [, rawPkgName, rev] = unpublishPackageMatch;
+      this.logger.log('debug', 'unpublishPackageMatch', { packageName: decodeURIComponent(rawPkgName), rev });
+      return this.unpublishPackage(decodeURIComponent(rawPkgName), token);
     }
 
     // Package version: /{package}/{version}
     const versionMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)\/([^\/]+)$/);
     if (versionMatch) {
-      const [, packageName, version] = versionMatch;
-      console.log(`[versionMatch] matched! packageName=${packageName}, version=${version}`);
-      return this.handlePackageVersion(packageName, version, token);
+      const [, rawPkgName, version] = versionMatch;
+      this.logger.log('debug', 'versionMatch', { packageName: decodeURIComponent(rawPkgName), version });
+      return this.handlePackageVersion(decodeURIComponent(rawPkgName), version, token, actor);
     }
 
     // Package operations: /{package}
     const packageMatch = path.match(/^\/(@?[^\/]+(?:\/[^\/]+)?)$/);
     if (packageMatch) {
-      const packageName = packageMatch[1];
-      console.log(`[packageMatch] matched! packageName=${packageName}`);
-      return this.handlePackage(context.method, packageName, context.body, context.query, token);
+      const packageName = decodeURIComponent(packageMatch[1]);
+      this.logger.log('debug', 'packageMatch', { packageName });
+      return this.handlePackage(context.method, packageName, context.body, context.query, token, actor);
     }
 
     return {
@@ -186,11 +243,12 @@ export class NpmRegistry extends BaseRegistry {
     packageName: string,
     body: any,
     query: Record<string, string>,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     switch (method) {
       case 'GET':
-        return this.getPackument(packageName, token, query);
+        return this.getPackument(packageName, token, query, actor);
       case 'PUT':
         return this.publishPackage(packageName, body, token);
       case 'DELETE':
@@ -207,15 +265,34 @@ export class NpmRegistry extends BaseRegistry {
   private async getPackument(
     packageName: string,
     token: IAuthToken | null,
-    query: Record<string, string>
+    query: Record<string, string>,
+    actor?: IRequestActor
   ): Promise<IResponse> {
-    const packument = await this.storage.getNpmPackument(packageName);
+    let packument = await this.storage.getNpmPackument(packageName);
     this.logger.log('debug', `getPackument: ${packageName}`, {
       packageName,
       found: !!packument,
       versions: packument ? Object.keys(packument.versions).length : 0
     });
 
+    // If not found locally, try upstream
+    if (!packument) {
+      const upstream = await this.getUpstreamForRequest(packageName, 'packument', 'GET', actor);
+      if (upstream) {
+        this.logger.log('debug', `getPackument: fetching from upstream`, { packageName });
+        const upstreamPackument = await upstream.fetchPackument(packageName);
+        if (upstreamPackument) {
+          this.logger.log('debug', `getPackument: found in upstream`, {
+            packageName,
+            versions: Object.keys(upstreamPackument.versions || {}).length
+          });
+          packument = upstreamPackument;
+          // Optionally cache the packument locally (without tarballs)
+          // We don't store tarballs here - they'll be fetched on demand
+        }
+      }
+    }
+
     if (!packument) {
       return {
         status: 404,
@@ -252,14 +329,28 @@ export class NpmRegistry extends BaseRegistry {
   private async handlePackageVersion(
     packageName: string,
     version: string,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
-    console.log(`[handlePackageVersion] packageName=${packageName}, version=${version}`);
-    const packument = await this.storage.getNpmPackument(packageName);
-    console.log(`[handlePackageVersion] packument found:`, !!packument);
+    this.logger.log('debug', 'handlePackageVersion', { packageName, version });
+    let packument = await this.storage.getNpmPackument(packageName);
+    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 not found locally, try upstream
+    if (!packument) {
+      const upstream = await this.getUpstreamForRequest(packageName, 'packument', 'GET', actor);
+      if (upstream) {
+        this.logger.log('debug', 'handlePackageVersion: fetching from upstream', { packageName });
+        const upstreamPackument = await upstream.fetchPackument(packageName);
+        if (upstreamPackument) {
+          packument = upstreamPackument;
+        }
+      }
+    }
+
     if (!packument) {
       return {
         status: 404,
@@ -526,10 +617,11 @@ export class NpmRegistry extends BaseRegistry {
   private async handleTarballDownload(
     packageName: string,
     filename: string,
-    token: IAuthToken | null
+    token: IAuthToken | null,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     // Extract version from filename: package-name-1.0.0.tgz
-    const versionMatch = filename.match(/-([\d.]+(?:-[a-z0-9.]+)?)\.tgz$/);
+    const versionMatch = filename.match(/-([\d.]+(?:-[a-z0-9.]+)?)\.tgz$/i);
     if (!versionMatch) {
       return {
         status: 400,
@@ -539,7 +631,40 @@ export class NpmRegistry extends BaseRegistry {
     }
 
     const version = versionMatch[1];
-    const tarball = await this.storage.getNpmTarball(packageName, version);
+
+    // Try local storage first (streaming)
+    const streamResult = await this.storage.getNpmTarballStream(packageName, version);
+    if (streamResult) {
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': streamResult.size.toString(),
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // If not found locally, try upstream
+    let tarball: Buffer | null = null;
+    const upstream = await this.getUpstreamForRequest(packageName, 'tarball', 'GET', actor);
+    if (upstream) {
+      this.logger.log('debug', 'handleTarballDownload: fetching from upstream', {
+        packageName,
+        version,
+      });
+      const upstreamTarball = await upstream.fetchTarball(packageName, version);
+      if (upstreamTarball) {
+        tarball = upstreamTarball;
+        // Cache the tarball locally for future requests
+        await this.storage.putNpmTarball(packageName, version, tarball);
+        this.logger.log('debug', 'handleTarballDownload: cached tarball locally', {
+          packageName,
+          version,
+          size: tarball.length,
+        });
+      }
+    }
 
     if (!tarball) {
       return {
@@ -621,7 +746,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/npm/classes.npmupstream.ts

@@ -0,0 +1,260 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamResult,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+import type { IPackument, INpmVersion } from './interfaces.npm.js';
+
+/**
+ * NPM-specific upstream implementation.
+ *
+ * Handles:
+ * - Package metadata (packument) fetching
+ * - Tarball proxying
+ * - Scoped package routing (@scope/* patterns)
+ * - NPM-specific URL rewriting
+ */
+export class NpmUpstream extends BaseUpstream {
+  protected readonly protocolName = 'npm';
+
+  /** Local registry URL for rewriting tarball URLs */
+  private readonly localRegistryUrl: string;
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    localRegistryUrl: string,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+    this.localRegistryUrl = localRegistryUrl;
+  }
+
+  /**
+   * Fetch a packument from upstream registries.
+   */
+  public async fetchPackument(packageName: string): Promise<IPackument | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'npm',
+      resource: packageName,
+      resourceType: 'packument',
+      path: `/${encodeURIComponent(packageName).replace('%40', '@')}`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    // Parse and process packument
+    let packument: IPackument;
+    if (Buffer.isBuffer(result.body)) {
+      packument = JSON.parse(result.body.toString('utf8'));
+    } else {
+      packument = result.body;
+    }
+
+    // Rewrite tarball URLs to point to local registry
+    packument = this.rewriteTarballUrls(packument);
+
+    return packument;
+  }
+
+  /**
+   * Fetch a specific version from upstream registries.
+   */
+  public async fetchVersion(packageName: string, version: string): Promise<INpmVersion | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'npm',
+      resource: packageName,
+      resourceType: 'version',
+      path: `/${encodeURIComponent(packageName).replace('%40', '@')}/${version}`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    let versionData: INpmVersion;
+    if (Buffer.isBuffer(result.body)) {
+      versionData = JSON.parse(result.body.toString('utf8'));
+    } else {
+      versionData = result.body;
+    }
+
+    // Rewrite tarball URL
+    if (versionData.dist?.tarball) {
+      versionData.dist.tarball = this.rewriteSingleTarballUrl(
+        packageName,
+        versionData.version,
+        versionData.dist.tarball,
+      );
+    }
+
+    return versionData;
+  }
+
+  /**
+   * Fetch a tarball from upstream registries.
+   */
+  public async fetchTarball(packageName: string, version: string): Promise<Buffer | null> {
+    // First, try to get the tarball URL from packument
+    const packument = await this.fetchPackument(packageName);
+    let tarballPath: string;
+
+    if (packument?.versions?.[version]?.dist?.tarball) {
+      // Extract path from original (upstream) tarball URL
+      const tarballUrl = packument.versions[version].dist.tarball;
+      try {
+        const url = new URL(tarballUrl);
+        tarballPath = url.pathname;
+      } catch {
+        // Fallback to standard NPM tarball path
+        tarballPath = this.buildTarballPath(packageName, version);
+      }
+    } else {
+      tarballPath = this.buildTarballPath(packageName, version);
+    }
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'npm',
+      resource: packageName,
+      resourceType: 'tarball',
+      path: tarballPath,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Search packages in upstream registries.
+   */
+  public async search(text: string, size: number = 20, from: number = 0): Promise<any | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'npm',
+      resource: '*',
+      resourceType: 'search',
+      path: '/-/v1/search',
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {
+        text,
+        size: size.toString(),
+        from: from.toString(),
+      },
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Build the standard NPM tarball path.
+   */
+  private buildTarballPath(packageName: string, version: string): string {
+    // NPM uses: /{package}/-/{package-name}-{version}.tgz
+    // For scoped packages: /@scope/name/-/name-version.tgz
+    if (packageName.startsWith('@')) {
+      const [scope, name] = packageName.split('/');
+      return `/${scope}/${name}/-/${name}-${version}.tgz`;
+    } else {
+      return `/${packageName}/-/${packageName}-${version}.tgz`;
+    }
+  }
+
+  /**
+   * Rewrite all tarball URLs in a packument to point to local registry.
+   */
+  private rewriteTarballUrls(packument: IPackument): IPackument {
+    if (!packument.versions) {
+      return packument;
+    }
+
+    const rewritten = { ...packument };
+    rewritten.versions = {};
+
+    for (const [version, versionData] of Object.entries(packument.versions)) {
+      const newVersionData = { ...versionData };
+      if (newVersionData.dist?.tarball) {
+        newVersionData.dist = {
+          ...newVersionData.dist,
+          tarball: this.rewriteSingleTarballUrl(
+            packument.name,
+            version,
+            newVersionData.dist.tarball,
+          ),
+        };
+      }
+      rewritten.versions[version] = newVersionData;
+    }
+
+    return rewritten;
+  }
+
+  /**
+   * Rewrite a single tarball URL to point to local registry.
+   */
+  private rewriteSingleTarballUrl(
+    packageName: string,
+    version: string,
+    _originalUrl: string,
+  ): string {
+    // Generate local tarball URL
+    // Format: {localRegistryUrl}/{package}/-/{package-name}-{version}.tgz
+    const safeName = packageName.replace('@', '').replace('/', '-');
+    return `${this.localRegistryUrl}/${packageName}/-/${safeName}-${version}.tgz`;
+  }
+
+  /**
+   * Override URL building for NPM-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    // NPM registries often don't have trailing slashes
+    let baseUrl = upstream.url;
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/npm/index.ts

@@ -3,4 +3,5 @@
  */
 
 export { NpmRegistry } from './classes.npmregistry.js';
+export { NpmUpstream } from './classes.npmupstream.js';
 export * from './interfaces.npm.js';

ts/oci/classes.ociregistry.ts

@@ -1,7 +1,11 @@
+import { Smartlog } from '@push.rocks/smartlog';
 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, IRegistryError } from '../core/interfaces.core.js';
+import type { IRequestContext, IResponse, IAuthToken, IRegistryError, IRequestActor } from '../core/interfaces.core.js';
+import { createHashTransform, streamToBuffer } from '../core/helpers.stream.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import { OciUpstream } from './classes.ociupstream.js';
 import type {
   IUploadSession,
   IOciManifest,
@@ -21,18 +25,78 @@ export class OciRegistry extends BaseRegistry {
   private basePath: string = '/oci';
   private cleanupInterval?: NodeJS.Timeout;
   private ociTokens?: { realm: string; service: string };
+  private upstreamProvider: IUpstreamProvider | null = null;
+  private logger: Smartlog;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/oci',
-    ociTokens?: { realm: string; service: string }
+    ociTokens?: { realm: string; service: string },
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.ociTokens = ociTokens;
+    this.upstreamProvider = upstreamProvider || null;
+
+    // Initialize logger
+    this.logger = new Smartlog({
+      logContext: {
+        company: 'push.rocks',
+        companyunit: 'smartregistry',
+        containerName: 'oci-registry',
+        environment: (process.env.NODE_ENV as any) || 'development',
+        runtime: 'node',
+        zone: 'oci'
+      }
+    });
+    this.logger.enableConsole();
+
+    if (upstreamProvider) {
+      this.logger.log('info', 'OCI upstream provider configured');
+    }
+  }
+
+  /**
+   * Extract scope from OCI repository name.
+   * @example "myorg/myimage" -> "myorg"
+   * @example "library/nginx" -> "library"
+   * @example "nginx" -> null
+   */
+  private extractScope(repository: string): string | null {
+    const slashIndex = repository.indexOf('/');
+    if (slashIndex > 0) {
+      return repository.substring(0, slashIndex);
+    }
+    return null;
+  }
+
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<OciUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'oci',
+      resource,
+      scope: this.extractScope(resource),
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new OciUpstream(config, this.basePath, this.logger);
   }
 
   public async init(): Promise<void> {
@@ -53,29 +117,37 @@ export class OciRegistry extends BaseRegistry {
     const tokenString = authHeader?.replace(/^Bearer\s+/i, '');
     const token = tokenString ? await this.authManager.validateToken(tokenString, 'oci') : null;
 
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     // Route to appropriate handler
-    if (path === '/v2/' || path === '/v2') {
+    if (path === '/' || path === '') {
       return this.handleVersionCheck();
     }
 
-    // Manifest operations: /v2/{name}/manifests/{reference}
-    const manifestMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/manifests\/([^\/]+)$/);
+    // Manifest operations: /{name}/manifests/{reference}
+    const manifestMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/manifests\/([^\/]+)$/);
     if (manifestMatch) {
       const [, name, reference] = manifestMatch;
       // Prefer rawBody for content-addressable operations to preserve exact bytes
       const bodyData = context.rawBody || context.body;
-      return this.handleManifestRequest(context.method, name, reference, token, bodyData, context.headers);
+      return this.handleManifestRequest(context.method, name, reference, token, bodyData, context.headers, actor);
     }
 
-    // Blob operations: /v2/{name}/blobs/{digest}
-    const blobMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/blobs\/(sha256:[a-f0-9]{64})$/);
+    // Blob operations: /{name}/blobs/{digest}
+    const blobMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/blobs\/(sha256:[a-f0-9]{64})$/);
     if (blobMatch) {
       const [, name, digest] = blobMatch;
-      return this.handleBlobRequest(context.method, name, digest, token, context.headers);
+      return this.handleBlobRequest(context.method, name, digest, token, context.headers, actor);
     }
 
-    // Blob upload operations: /v2/{name}/blobs/uploads/
-    const uploadInitMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/blobs\/uploads\/?$/);
+    // Blob upload operations: /{name}/blobs/uploads/
+    const uploadInitMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/blobs\/uploads\/?$/);
     if (uploadInitMatch && context.method === 'POST') {
       const [, name] = uploadInitMatch;
       // Prefer rawBody for content-addressable operations to preserve exact bytes
@@ -83,22 +155,22 @@ export class OciRegistry extends BaseRegistry {
       return this.handleUploadInit(name, token, context.query, bodyData);
     }
 
-    // Blob upload operations: /v2/{name}/blobs/uploads/{uuid}
-    const uploadMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/blobs\/uploads\/([^\/]+)$/);
+    // Blob upload operations: /{name}/blobs/uploads/{uuid}
+    const uploadMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/blobs\/uploads\/([^\/]+)$/);
     if (uploadMatch) {
       const [, name, uploadId] = uploadMatch;
       return this.handleUploadSession(context.method, uploadId, token, context);
     }
 
-    // Tags list: /v2/{name}/tags/list
-    const tagsMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/tags\/list$/);
+    // Tags list: /{name}/tags/list
+    const tagsMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/tags\/list$/);
     if (tagsMatch) {
       const [, name] = tagsMatch;
       return this.handleTagsList(name, token, context.query);
     }
 
-    // Referrers: /v2/{name}/referrers/{digest}
-    const referrersMatch = path.match(/^\/v2\/([^\/]+(?:\/[^\/]+)*)\/referrers\/(sha256:[a-f0-9]{64})$/);
+    // Referrers: /{name}/referrers/{digest}
+    const referrersMatch = path.match(/^\/([^\/]+(?:\/[^\/]+)*)\/referrers\/(sha256:[a-f0-9]{64})$/);
     if (referrersMatch) {
       const [, name, digest] = referrersMatch;
       return this.handleReferrers(name, digest, token, context.query);
@@ -141,11 +213,12 @@ export class OciRegistry extends BaseRegistry {
     reference: string,
     token: IAuthToken | null,
     body?: Buffer | any,
-    headers?: Record<string, string>
+    headers?: Record<string, string>,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     switch (method) {
       case 'GET':
-        return this.getManifest(repository, reference, token, headers);
+        return this.getManifest(repository, reference, token, headers, actor);
       case 'HEAD':
         return this.headManifest(repository, reference, token);
       case 'PUT':
@@ -166,11 +239,12 @@ export class OciRegistry extends BaseRegistry {
     repository: string,
     digest: string,
     token: IAuthToken | null,
-    headers: Record<string, string>
+    headers: Record<string, string>,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     switch (method) {
       case 'GET':
-        return this.getBlob(repository, digest, token, headers['range'] || headers['Range']);
+        return this.getBlob(repository, digest, token, headers['range'] || headers['Range'], actor);
       case 'HEAD':
         return this.headBlob(repository, digest, token);
       case 'DELETE':
@@ -216,7 +290,7 @@ export class OciRegistry extends BaseRegistry {
       return {
         status: 201,
         headers: {
-          'Location': `${this.basePath}/v2/${repository}/blobs/${digest}`,
+          'Location': `${this.basePath}/${repository}/blobs/${digest}`,
           'Docker-Content-Digest': digest,
         },
         body: null,
@@ -229,6 +303,8 @@ export class OciRegistry extends BaseRegistry {
       uploadId,
       repository,
       chunks: [],
+      chunkPaths: [],
+      chunkIndex: 0,
       totalSize: 0,
       createdAt: new Date(),
       lastActivity: new Date(),
@@ -239,7 +315,7 @@ export class OciRegistry extends BaseRegistry {
     return {
       status: 202,
       headers: {
-        'Location': `${this.basePath}/v2/${repository}/blobs/uploads/${uploadId}`,
+        'Location': `${this.basePath}/${repository}/blobs/uploads/${uploadId}`,
         'Docker-Upload-UUID': uploadId,
       },
       body: null,
@@ -291,7 +367,8 @@ export class OciRegistry extends BaseRegistry {
     repository: string,
     reference: string,
     token: IAuthToken | null,
-    headers?: Record<string, string>
+    headers?: Record<string, string>,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     if (!await this.checkPermission(token, repository, 'pull')) {
       return this.createUnauthorizedResponse(repository, 'pull');
@@ -302,16 +379,53 @@ export class OciRegistry extends BaseRegistry {
     if (!reference.startsWith('sha256:')) {
       const tags = await this.getTagsData(repository);
       digest = tags[reference];
-      if (!digest) {
-        return {
-          status: 404,
-          headers: {},
-          body: this.createError('MANIFEST_UNKNOWN', 'Manifest not found'),
-        };
+    }
+
+    // Try local storage first (if we have a digest)
+    let manifestData: Buffer | null = null;
+    let contentType: string | null = null;
+
+    if (digest) {
+      manifestData = await this.storage.getOciManifest(repository, digest);
+      if (manifestData) {
+        contentType = await this.storage.getOciManifestContentType(repository, digest);
+        if (!contentType) {
+          contentType = this.detectManifestContentType(manifestData);
+        }
+      }
+    }
+
+    // If not found locally, try upstream
+    if (!manifestData) {
+      const upstream = await this.getUpstreamForRequest(repository, 'manifest', 'GET', actor);
+      if (upstream) {
+        this.logger.log('debug', 'getManifest: fetching from upstream', { repository, reference });
+        const upstreamResult = await upstream.fetchManifest(repository, reference);
+        if (upstreamResult) {
+          manifestData = Buffer.from(JSON.stringify(upstreamResult.manifest), 'utf8');
+          contentType = upstreamResult.contentType;
+          digest = upstreamResult.digest;
+
+          // Cache the manifest locally
+          await this.storage.putOciManifest(repository, digest, manifestData, contentType);
+
+          // If reference is a tag, update tags mapping
+          if (!reference.startsWith('sha256:')) {
+            const tags = await this.getTagsData(repository);
+            tags[reference] = digest;
+            const tagsPath = `oci/tags/${repository}/tags.json`;
+            await this.storage.putObject(tagsPath, Buffer.from(JSON.stringify(tags), 'utf-8'));
+          }
+
+          this.logger.log('debug', 'getManifest: cached manifest locally', {
+            repository,
+            reference,
+            digest,
+          });
+        }
       }
     }
 
-    const manifestData = await this.storage.getOciManifest(repository, digest);
     if (!manifestData) {
       return {
         status: 404,
@@ -320,17 +434,10 @@ 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': contentType,
+        'Content-Type': contentType || 'application/vnd.oci.image.manifest.v1+json',
         'Docker-Content-Digest': digest,
       },
       body: manifestData,
@@ -423,7 +530,7 @@ export class OciRegistry extends BaseRegistry {
     return {
       status: 201,
       headers: {
-        'Location': `${this.basePath}/v2/${repository}/manifests/${digest}`,
+        'Location': `${this.basePath}/${repository}/manifests/${digest}`,
         'Docker-Content-Digest': digest,
       },
       body: null,
@@ -460,13 +567,45 @@ export class OciRegistry extends BaseRegistry {
     repository: string,
     digest: string,
     token: IAuthToken | null,
-    range?: string
+    range?: string,
+    actor?: IRequestActor
   ): Promise<IResponse> {
     if (!await this.checkPermission(token, repository, 'pull')) {
       return this.createUnauthorizedResponse(repository, 'pull');
     }
 
-    const data = await this.storage.getOciBlob(digest);
+    // Try local storage first (streaming)
+    const streamResult = await this.storage.getOciBlobStream(digest);
+    if (streamResult) {
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Length': streamResult.size.toString(),
+          'Docker-Content-Digest': digest,
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // If not found locally, try upstream
+    let data: Buffer | null = null;
+    const upstream = await this.getUpstreamForRequest(repository, 'blob', 'GET', actor);
+    if (upstream) {
+      this.logger.log('debug', 'getBlob: fetching from upstream', { repository, digest });
+      const upstreamBlob = await upstream.fetchBlob(repository, digest);
+      if (upstreamBlob) {
+        data = upstreamBlob;
+        // Cache the blob locally (blobs are content-addressable and immutable)
+        await this.storage.putOciBlob(digest, data);
+        this.logger.log('debug', 'getBlob: cached blob locally', {
+          repository,
+          digest,
+          size: data.length,
+        });
+      }
+    }
+
     if (!data) {
       return {
         status: 404,
@@ -494,17 +633,15 @@ export class OciRegistry extends BaseRegistry {
       return this.createUnauthorizedHeadResponse(repository, 'pull');
     }
 
-    const exists = await this.storage.ociBlobExists(digest);
-    if (!exists) {
+    const blobSize = await this.storage.getOciBlobSize(digest);
+    if (blobSize === null) {
       return { status: 404, headers: {}, body: null };
     }
 
-    const blob = await this.storage.getOciBlob(digest);
-
     return {
       status: 200,
       headers: {
-        'Content-Length': blob ? blob.length.toString() : '0',
+        'Content-Length': blobSize.toString(),
         'Docker-Content-Digest': digest,
       },
       body: null,
@@ -544,14 +681,19 @@ export class OciRegistry extends BaseRegistry {
     }
 
     const chunkData = this.toBuffer(data);
-    session.chunks.push(chunkData);
+
+    // Write chunk to temp S3 object instead of accumulating in memory
+    const chunkPath = `oci/uploads/${uploadId}/chunk-${session.chunkIndex}`;
+    await this.storage.putObject(chunkPath, chunkData);
+    session.chunkPaths.push(chunkPath);
+    session.chunkIndex++;
     session.totalSize += chunkData.length;
     session.lastActivity = new Date();
 
     return {
       status: 202,
       headers: {
-        'Location': `${this.basePath}/v2/${session.repository}/blobs/uploads/${uploadId}`,
+        'Location': `${this.basePath}/${session.repository}/blobs/uploads/${uploadId}`,
         'Range': `0-${session.totalSize - 1}`,
         'Docker-Upload-UUID': uploadId,
       },
@@ -573,13 +715,52 @@ export class OciRegistry extends BaseRegistry {
       };
     }
 
-    const chunks = [...session.chunks];
-    if (finalData) chunks.push(this.toBuffer(finalData));
-    const blobData = Buffer.concat(chunks);
+    // If there's final data in the PUT body, write it as the last chunk
+    if (finalData) {
+      const buf = this.toBuffer(finalData);
+      const chunkPath = `oci/uploads/${uploadId}/chunk-${session.chunkIndex}`;
+      await this.storage.putObject(chunkPath, buf);
+      session.chunkPaths.push(chunkPath);
+      session.chunkIndex++;
+      session.totalSize += buf.length;
+    }
 
-    // Verify digest
-    const calculatedDigest = await this.calculateDigest(blobData);
+    // Create a ReadableStream that assembles all chunks from S3 sequentially
+    const chunkPaths = [...session.chunkPaths];
+    const storage = this.storage;
+    let chunkIdx = 0;
+    const assembledStream = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        if (chunkIdx >= chunkPaths.length) {
+          controller.close();
+          return;
+        }
+        const result = await storage.getObjectStream(chunkPaths[chunkIdx++]);
+        if (result) {
+          const reader = result.stream.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (value) controller.enqueue(value);
+          }
+        }
+      },
+    });
+
+    // Pipe through hash transform for incremental digest verification
+    const { transform: hashTransform, getDigest } = createHashTransform('sha256');
+    const hashedStream = assembledStream.pipeThrough(hashTransform);
+
+    // Consume stream to buffer for S3 upload
+    // (AWS SDK PutObjectCommand requires known content-length for streams;
+    //  the key win is chunks are NOT accumulated in memory during PATCH — they live in S3)
+    const blobData = await streamToBuffer(hashedStream);
+
+    // Verify digest before storing
+    const calculatedDigest = `sha256:${getDigest()}`;
     if (calculatedDigest !== digest) {
+      await this.cleanupUploadChunks(session);
+      this.uploadSessions.delete(uploadId);
       return {
         status: 400,
         headers: {},
@@ -587,19 +768,36 @@ export class OciRegistry extends BaseRegistry {
       };
     }
 
+    // Store verified blob
     await this.storage.putOciBlob(digest, blobData);
+
+    // Cleanup temp chunks and session
+    await this.cleanupUploadChunks(session);
     this.uploadSessions.delete(uploadId);
 
     return {
       status: 201,
       headers: {
-        'Location': `${this.basePath}/v2/${session.repository}/blobs/${digest}`,
+        'Location': `${this.basePath}/${session.repository}/blobs/${digest}`,
         'Docker-Content-Digest': digest,
       },
       body: null,
     };
   }
 
+  /**
+   * Delete all temp S3 chunk objects for an upload session.
+   */
+  private async cleanupUploadChunks(session: IUploadSession): Promise<void> {
+    for (const chunkPath of session.chunkPaths) {
+      try {
+        await this.storage.deleteObject(chunkPath);
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+  }
+
   private async getUploadStatus(uploadId: string): Promise<IResponse> {
     const session = this.uploadSessions.get(uploadId);
     if (!session) {
@@ -613,7 +811,7 @@ export class OciRegistry extends BaseRegistry {
     return {
       status: 204,
       headers: {
-        'Location': `${this.basePath}/v2/${session.repository}/blobs/uploads/${uploadId}`,
+        'Location': `${this.basePath}/${session.repository}/blobs/uploads/${uploadId}`,
         'Range': session.totalSize > 0 ? `0-${session.totalSize - 1}` : '0-0',
         'Docker-Upload-UUID': uploadId,
       },
@@ -738,7 +936,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> {
@@ -758,7 +956,7 @@ export class OciRegistry extends BaseRegistry {
    * Per OCI Distribution Spec, 401 responses MUST include WWW-Authenticate header.
    */
   private createUnauthorizedResponse(repository: string, action: string): IResponse {
-    const realm = this.ociTokens?.realm || `${this.basePath}/v2/token`;
+    const realm = this.ociTokens?.realm || `${this.basePath}/token`;
     const service = this.ociTokens?.service || 'registry';
     return {
       status: 401,
@@ -773,7 +971,7 @@ export class OciRegistry extends BaseRegistry {
    * Create an unauthorized HEAD response (no body per HTTP spec).
    */
   private createUnauthorizedHeadResponse(repository: string, action: string): IResponse {
-    const realm = this.ociTokens?.realm || `${this.basePath}/v2/token`;
+    const realm = this.ociTokens?.realm || `${this.basePath}/token`;
     const service = this.ociTokens?.service || 'registry';
     return {
       status: 401,
@@ -791,6 +989,8 @@ export class OciRegistry extends BaseRegistry {
 
       for (const [uploadId, session] of this.uploadSessions.entries()) {
         if (now.getTime() - session.lastActivity.getTime() > maxAge) {
+          // Clean up temp S3 chunks for stale sessions
+          this.cleanupUploadChunks(session).catch(() => {});
           this.uploadSessions.delete(uploadId);
         }
       }

ts/oci/classes.ociupstream.ts

@@ -0,0 +1,273 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamResult,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+import type { IOciManifest, IOciImageIndex, ITagList } from './interfaces.oci.js';
+
+/**
+ * OCI-specific upstream implementation.
+ *
+ * Handles:
+ * - Manifest fetching (image manifests and index manifests)
+ * - Blob proxying (layers, configs)
+ * - Tag list fetching
+ * - Content-addressable caching (blobs are immutable)
+ * - Docker Hub authentication flow
+ */
+export class OciUpstream extends BaseUpstream {
+  protected readonly protocolName = 'oci';
+
+  /** Local registry base path for URL building */
+  private readonly localBasePath: string;
+
+  /** API prefix for outbound OCI requests (default: /v2) */
+  private readonly apiPrefix: string;
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    localBasePath: string = '/oci',
+    logger?: plugins.smartlog.Smartlog,
+    apiPrefix: string = '/v2',
+  ) {
+    super(config, logger);
+    this.localBasePath = localBasePath;
+    this.apiPrefix = apiPrefix;
+  }
+
+  /**
+   * Fetch a manifest from upstream registries.
+   */
+  public async fetchManifest(
+    repository: string,
+    reference: string,
+  ): Promise<{ manifest: IOciManifest | IOciImageIndex; contentType: string; digest: string } | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'oci',
+      resource: repository,
+      resourceType: 'manifest',
+      path: `${this.apiPrefix}/${repository}/manifests/${reference}`,
+      method: 'GET',
+      headers: {
+        'accept': [
+          'application/vnd.oci.image.manifest.v1+json',
+          'application/vnd.oci.image.index.v1+json',
+          'application/vnd.docker.distribution.manifest.v2+json',
+          'application/vnd.docker.distribution.manifest.list.v2+json',
+          'application/vnd.docker.distribution.manifest.v1+json',
+        ].join(', '),
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    let manifest: IOciManifest | IOciImageIndex;
+    if (Buffer.isBuffer(result.body)) {
+      manifest = JSON.parse(result.body.toString('utf8'));
+    } else {
+      manifest = result.body;
+    }
+
+    const contentType = result.headers['content-type'] || 'application/vnd.oci.image.manifest.v1+json';
+    const digest = result.headers['docker-content-digest'] || '';
+
+    return { manifest, contentType, digest };
+  }
+
+  /**
+   * Check if a manifest exists in upstream (HEAD request).
+   */
+  public async headManifest(
+    repository: string,
+    reference: string,
+  ): Promise<{ exists: boolean; contentType?: string; digest?: string; size?: number } | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'oci',
+      resource: repository,
+      resourceType: 'manifest',
+      path: `${this.apiPrefix}/${repository}/manifests/${reference}`,
+      method: 'HEAD',
+      headers: {
+        'accept': [
+          'application/vnd.oci.image.manifest.v1+json',
+          'application/vnd.oci.image.index.v1+json',
+          'application/vnd.docker.distribution.manifest.v2+json',
+          'application/vnd.docker.distribution.manifest.list.v2+json',
+        ].join(', '),
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result) {
+      return null;
+    }
+
+    if (!result.success) {
+      return { exists: false };
+    }
+
+    return {
+      exists: true,
+      contentType: result.headers['content-type'],
+      digest: result.headers['docker-content-digest'],
+      size: result.headers['content-length'] ? parseInt(result.headers['content-length'], 10) : undefined,
+    };
+  }
+
+  /**
+   * Fetch a blob from upstream registries.
+   */
+  public async fetchBlob(repository: string, digest: string): Promise<Buffer | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'oci',
+      resource: repository,
+      resourceType: 'blob',
+      path: `${this.apiPrefix}/${repository}/blobs/${digest}`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Check if a blob exists in upstream (HEAD request).
+   */
+  public async headBlob(
+    repository: string,
+    digest: string,
+  ): Promise<{ exists: boolean; size?: number } | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'oci',
+      resource: repository,
+      resourceType: 'blob',
+      path: `${this.apiPrefix}/${repository}/blobs/${digest}`,
+      method: 'HEAD',
+      headers: {},
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result) {
+      return null;
+    }
+
+    if (!result.success) {
+      return { exists: false };
+    }
+
+    return {
+      exists: true,
+      size: result.headers['content-length'] ? parseInt(result.headers['content-length'], 10) : undefined,
+    };
+  }
+
+  /**
+   * Fetch the tag list for a repository.
+   */
+  public async fetchTags(repository: string, n?: number, last?: string): Promise<ITagList | null> {
+    const query: Record<string, string> = {};
+    if (n) query.n = n.toString();
+    if (last) query.last = last;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'oci',
+      resource: repository,
+      resourceType: 'tags',
+      path: `${this.apiPrefix}/${repository}/tags/list`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query,
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    let tagList: ITagList;
+    if (Buffer.isBuffer(result.body)) {
+      tagList = JSON.parse(result.body.toString('utf8'));
+    } else {
+      tagList = result.body;
+    }
+
+    return tagList;
+  }
+
+  /**
+   * Override URL building for OCI-specific handling.
+   * OCI registries use a configurable API prefix (default /v2/) and may require
+   * special handling for Docker Hub.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    // Use per-upstream apiPrefix if configured, otherwise use the instance default
+    const prefix = upstream.apiPrefix || this.apiPrefix;
+
+    // Handle Docker Hub special case
+    // Docker Hub uses registry-1.docker.io but library images need special handling
+    if (baseUrl.includes('docker.io') || baseUrl.includes('registry-1.docker.io')) {
+      // For library images (e.g., "nginx" -> "library/nginx")
+      const escapedPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const pathParts = context.path.match(new RegExp(`^${escapedPrefix}\\/([^\\/]+)\\/(.+)$`));
+      if (pathParts) {
+        const [, repository, rest] = pathParts;
+        // If repository doesn't contain a slash, it's a library image
+        if (!repository.includes('/')) {
+          return `${baseUrl}${prefix}/library/${repository}/${rest}`;
+        }
+      }
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+
+  /**
+   * Override header building for OCI-specific authentication.
+   * OCI registries may require token-based auth obtained from a separate endpoint.
+   */
+  protected buildHeaders(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): Record<string, string> {
+    const headers = super.buildHeaders(upstream, context);
+
+    // OCI registries typically use Docker-Distribution-API-Version header
+    headers['docker-distribution-api-version'] = 'registry/2.0';
+
+    return headers;
+  }
+}

ts/oci/index.ts

@@ -3,4 +3,5 @@
  */
 
 export { OciRegistry } from './classes.ociregistry.js';
+export { OciUpstream } from './classes.ociupstream.js';
 export * from './interfaces.oci.js';

ts/oci/interfaces.oci.ts

@@ -62,6 +62,10 @@ export interface IUploadSession {
   uploadId: string;
   repository: string;
   chunks: Buffer[];
+  /** S3 paths to temp chunk objects (streaming mode) */
+  chunkPaths: string[];
+  /** Index counter for naming temp chunk objects */
+  chunkIndex: number;
   totalSize: number;
   createdAt: Date;
   lastActivity: Date;

ts/plugins.ts

@@ -8,10 +8,16 @@ import * as smartarchive from '@push.rocks/smartarchive';
 import * as smartbucket from '@push.rocks/smartbucket';
 import * as smartlog from '@push.rocks/smartlog';
 import * as smartpath from '@push.rocks/smartpath';
+import * as smartrequest from '@push.rocks/smartrequest';
 
-export { smartarchive, smartbucket, smartlog, smartpath };
+export { smartarchive, smartbucket, smartlog, smartpath, smartrequest };
 
 // @tsclass scope
 import * as tsclass from '@tsclass/tsclass';
 
 export { tsclass };
+
+// third party
+import { minimatch } from 'minimatch';
+
+export { minimatch };

ts/pypi/classes.pypiregistry.ts

@@ -2,7 +2,9 @@ import { Smartlog } from '@push.rocks/smartlog';
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
+import { isBinaryData, toBuffer } from '../core/helpers.buffer.js';
 import type {
   IPypiPackageMetadata,
   IPypiFile,
@@ -10,6 +12,7 @@ import type {
   IPypiUploadResponse,
 } from './interfaces.pypi.js';
 import * as helpers from './helpers.pypi.js';
+import { PypiUpstream } from './classes.pypiupstream.js';
 
 /**
  * PyPI registry implementation
@@ -21,18 +24,21 @@ export class PypiRegistry extends BaseRegistry {
   private basePath: string = '/pypi';
   private registryUrl: string;
   private logger: Smartlog;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/pypi',
-    registryUrl: string = 'http://localhost:5000'
+    registryUrl: string = 'http://localhost:5000',
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
 
     // Initialize logger
     this.logger = new Smartlog({
@@ -48,6 +54,38 @@ export class PypiRegistry extends BaseRegistry {
     this.logger.enableConsole();
   }
 
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<PypiUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'pypi',
+      resource,
+      scope: resource, // For PyPI, package name is the scope
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new PypiUpstream(config, this.registryUrl, this.logger);
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    // No persistent upstream to clean up with dynamic provider
+  }
+
   public async init(): Promise<void> {
     // Initialize root Simple API index if not exists
     const existingIndex = await this.storage.getPypiSimpleRootIndex();
@@ -65,15 +103,23 @@ export class PypiRegistry extends BaseRegistry {
   public async handleRequest(context: IRequestContext): Promise<IResponse> {
     let path = context.path.replace(this.basePath, '');
 
+    // Extract token (Basic Auth or Bearer)
+    const token = await this.extractToken(context);
+
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     // Also handle /simple path prefix
     if (path.startsWith('/simple')) {
       path = path.replace('/simple', '');
-      return this.handleSimpleRequest(path, context);
+      return this.handleSimpleRequest(path, context, actor);
     }
 
-    // Extract token (Basic Auth or Bearer)
-    const token = await this.extractToken(context);
-
     this.logger.log('debug', `handleRequest: ${context.method} ${path}`, {
       method: context.method,
       path,
@@ -100,7 +146,7 @@ export class PypiRegistry extends BaseRegistry {
     // Package file download: GET /packages/{package}/{filename}
     const downloadMatch = path.match(/^\/packages\/([^\/]+)\/(.+)$/);
     if (downloadMatch && context.method === 'GET') {
-      return this.handleDownload(downloadMatch[1], downloadMatch[2]);
+      return this.handleDownload(downloadMatch[1], downloadMatch[2], actor);
     }
 
     // Delete package: DELETE /packages/{package}
@@ -137,7 +183,7 @@ export class PypiRegistry extends BaseRegistry {
   /**
    * Handle Simple API requests (PEP 503 HTML or PEP 691 JSON)
    */
-  private async handleSimpleRequest(path: string, context: IRequestContext): Promise<IResponse> {
+  private async handleSimpleRequest(path: string, context: IRequestContext, actor?: IRequestActor): Promise<IResponse> {
     // Ensure path ends with / (PEP 503 requirement)
     if (!path.endsWith('/') && !path.includes('.')) {
       return {
@@ -155,7 +201,7 @@ export class PypiRegistry extends BaseRegistry {
     // Package index: /simple/{package}/
     const packageMatch = path.match(/^\/([^\/]+)\/$/);
     if (packageMatch) {
-      return this.handleSimplePackage(packageMatch[1], context);
+      return this.handleSimplePackage(packageMatch[1], context, actor);
     }
 
     return {
@@ -209,11 +255,52 @@ export class PypiRegistry extends BaseRegistry {
    * Handle Simple API package index
    * Returns HTML (PEP 503) or JSON (PEP 691) based on Accept header
    */
-  private async handleSimplePackage(packageName: string, context: IRequestContext): Promise<IResponse> {
+  private async handleSimplePackage(packageName: string, context: IRequestContext, actor?: IRequestActor): Promise<IResponse> {
     const normalized = helpers.normalizePypiPackageName(packageName);
 
     // Get package metadata
-    const metadata = await this.storage.getPypiPackageMetadata(normalized);
+    let metadata = await this.storage.getPypiPackageMetadata(normalized);
+
+    // Try upstream if not found locally
+    if (!metadata) {
+      const upstream = await this.getUpstreamForRequest(normalized, 'simple', 'GET', actor);
+      if (upstream) {
+        const upstreamHtml = await upstream.fetchSimplePackage(normalized);
+        if (upstreamHtml) {
+          // Parse the HTML to extract file information and cache it
+          // For now, just return the upstream HTML directly (caching can be improved later)
+          const acceptHeader = context.headers['accept'] || context.headers['Accept'] || '';
+          const preferJson = acceptHeader.includes('application/vnd.pypi.simple') &&
+                             acceptHeader.includes('json');
+
+          if (preferJson) {
+            // Try to get JSON format from upstream
+            const upstreamJson = await upstream.fetchPackageJson(normalized);
+            if (upstreamJson) {
+              return {
+                status: 200,
+                headers: {
+                  'Content-Type': 'application/vnd.pypi.simple.v1+json',
+                  'Cache-Control': 'public, max-age=300'
+                },
+                body: upstreamJson,
+              };
+            }
+          }
+
+          // Return HTML format
+          return {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/html; charset=utf-8',
+              'Cache-Control': 'public, max-age=300'
+            },
+            body: upstreamHtml,
+          };
+        }
+      }
+    }
+
     if (!metadata) {
       return this.errorResponse(404, 'Package not found');
     }
@@ -328,8 +415,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)
-      const fileData = (formData.content?.data || (Buffer.isBuffer(formData.content) ? formData.content : null)) as Buffer;
+      // Support both: formData.content.data (multipart parsed) and formData.content (Buffer/Uint8Array directly)
+      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;
 
@@ -445,9 +533,34 @@ export class PypiRegistry extends BaseRegistry {
   /**
    * Handle package download
    */
-  private async handleDownload(packageName: string, filename: string): Promise<IResponse> {
+  private async handleDownload(packageName: string, filename: string, actor?: IRequestActor): Promise<IResponse> {
     const normalized = helpers.normalizePypiPackageName(packageName);
-    const fileData = await this.storage.getPypiPackageFile(normalized, filename);
+
+    // Try streaming from local storage first
+    const streamResult = await this.storage.getPypiPackageFileStream(normalized, filename);
+
+    if (streamResult) {
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Disposition': `attachment; filename="${filename}"`,
+          'Content-Length': streamResult.size.toString()
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // Try upstream if not found locally
+    let fileData: Buffer | null = null;
+    const upstream = await this.getUpstreamForRequest(normalized, 'file', 'GET', actor);
+    if (upstream) {
+      fileData = await upstream.fetchPackageFile(normalized, filename);
+      if (fileData) {
+        // Cache locally
+        await this.storage.putPypiPackageFile(normalized, filename, fileData);
+      }
+    }
 
     if (!fileData) {
       return {

ts/pypi/classes.pypiupstream.ts

@@ -0,0 +1,211 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+
+/**
+ * PyPI-specific upstream implementation.
+ *
+ * Handles:
+ * - Simple API (HTML) - PEP 503
+ * - JSON API - PEP 691
+ * - Package file downloads (wheels, sdists)
+ * - Package name normalization
+ */
+export class PypiUpstream extends BaseUpstream {
+  protected readonly protocolName = 'pypi';
+
+  /** Local registry URL for rewriting download URLs */
+  private readonly localRegistryUrl: string;
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    localRegistryUrl: string,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+    this.localRegistryUrl = localRegistryUrl;
+  }
+
+  /**
+   * Fetch Simple API index (list of all packages) in HTML format.
+   */
+  public async fetchSimpleIndex(): Promise<string | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'pypi',
+      resource: '*',
+      resourceType: 'index',
+      path: '/simple/',
+      method: 'GET',
+      headers: {
+        'accept': 'text/html',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch Simple API package page (list of files) in HTML format.
+   */
+  public async fetchSimplePackage(packageName: string): Promise<string | null> {
+    const normalizedName = this.normalizePackageName(packageName);
+    const path = `/simple/${normalizedName}/`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'pypi',
+      resource: packageName,
+      resourceType: 'simple',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'text/html',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch package metadata using JSON API (PEP 691).
+   */
+  public async fetchPackageJson(packageName: string): Promise<any | null> {
+    const normalizedName = this.normalizePackageName(packageName);
+    const path = `/simple/${normalizedName}/`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'pypi',
+      resource: packageName,
+      resourceType: 'metadata',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/vnd.pypi.simple.v1+json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch full package info from PyPI JSON API (/pypi/{package}/json).
+   */
+  public async fetchPypiJson(packageName: string): Promise<any | null> {
+    const normalizedName = this.normalizePackageName(packageName);
+    const path = `/pypi/${normalizedName}/json`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'pypi',
+      resource: packageName,
+      resourceType: 'pypi-json',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return result.body;
+  }
+
+  /**
+   * Fetch a package file (wheel or sdist) from upstream.
+   */
+  public async fetchPackageFile(packageName: string, filename: string): Promise<Buffer | null> {
+    const normalizedName = this.normalizePackageName(packageName);
+    const path = `/packages/${normalizedName}/${filename}`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'pypi',
+      resource: packageName,
+      resourceType: 'package',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Normalize a PyPI package name according to PEP 503.
+   * - Lowercase all characters
+   * - Replace runs of ., -, _ with single -
+   */
+  private normalizePackageName(name: string): string {
+    return name.toLowerCase().replace(/[-_.]+/g, '-');
+  }
+
+  /**
+   * Override URL building for PyPI-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/pypi/index.ts

@@ -5,4 +5,5 @@
 
 export * from './interfaces.pypi.js';
 export * from './classes.pypiregistry.js';
+export { PypiUpstream } from './classes.pypiupstream.js';
 export * as pypiHelpers from './helpers.pypi.js';

ts/rubygems/classes.rubygemsregistry.ts

@@ -2,7 +2,8 @@ import { Smartlog } from '@push.rocks/smartlog';
 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 type { IRequestContext, IResponse, IAuthToken, IRequestActor } from '../core/interfaces.core.js';
+import type { IUpstreamProvider } from '../upstream/interfaces.upstream.js';
 import type {
   IRubyGemsMetadata,
   IRubyGemsVersionMetadata,
@@ -12,6 +13,7 @@ import type {
   ICompactIndexInfoEntry,
 } from './interfaces.rubygems.js';
 import * as helpers from './helpers.rubygems.js';
+import { RubygemsUpstream } from './classes.rubygemsupstream.js';
 
 /**
  * RubyGems registry implementation
@@ -23,18 +25,21 @@ export class RubyGemsRegistry extends BaseRegistry {
   private basePath: string = '/rubygems';
   private registryUrl: string;
   private logger: Smartlog;
+  private upstreamProvider: IUpstreamProvider | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/rubygems',
-    registryUrl: string = 'http://localhost:5000/rubygems'
+    registryUrl: string = 'http://localhost:5000/rubygems',
+    upstreamProvider?: IUpstreamProvider
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+    this.upstreamProvider = upstreamProvider || null;
 
     // Initialize logger
     this.logger = new Smartlog({
@@ -50,6 +55,38 @@ export class RubyGemsRegistry extends BaseRegistry {
     this.logger.enableConsole();
   }
 
+  /**
+   * Get upstream for a specific request.
+   * Calls the provider to resolve upstream config dynamically.
+   */
+  private async getUpstreamForRequest(
+    resource: string,
+    resourceType: string,
+    method: string,
+    actor?: IRequestActor
+  ): Promise<RubygemsUpstream | null> {
+    if (!this.upstreamProvider) return null;
+
+    const config = await this.upstreamProvider.resolveUpstreamConfig({
+      protocol: 'rubygems',
+      resource,
+      scope: resource, // gem name is the scope
+      actor,
+      method,
+      resourceType,
+    });
+
+    if (!config?.enabled) return null;
+    return new RubygemsUpstream(config, this.logger);
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    // No persistent upstream to clean up with dynamic provider
+  }
+
   public async init(): Promise<void> {
     // Initialize Compact Index files if not exist
     const existingVersions = await this.storage.getRubyGemsVersions();
@@ -77,6 +114,14 @@ export class RubyGemsRegistry extends BaseRegistry {
     // Extract token (Authorization header)
     const token = await this.extractToken(context);
 
+    // Build actor from context and validated token
+    const actor: IRequestActor = {
+      ...context.actor,
+      userId: token?.userId,
+      ip: context.headers['x-forwarded-for'] || context.headers['X-Forwarded-For'],
+      userAgent: context.headers['user-agent'] || context.headers['User-Agent'],
+    };
+
     this.logger.log('debug', `handleRequest: ${context.method} ${path}`, {
       method: context.method,
       path,
@@ -95,13 +140,13 @@ export class RubyGemsRegistry extends BaseRegistry {
     // Info file: GET /info/{gem}
     const infoMatch = path.match(/^\/info\/([^\/]+)$/);
     if (infoMatch && context.method === 'GET') {
-      return this.handleInfoFile(infoMatch[1]);
+      return this.handleInfoFile(infoMatch[1], actor);
     }
 
     // Gem download: GET /gems/{gem}-{version}[-{platform}].gem
     const downloadMatch = path.match(/^\/gems\/(.+\.gem)$/);
     if (downloadMatch && context.method === 'GET') {
-      return this.handleDownload(downloadMatch[1]);
+      return this.handleDownload(downloadMatch[1], actor);
     }
 
     // Legacy specs endpoints (Marshal format)
@@ -214,8 +259,21 @@ export class RubyGemsRegistry extends BaseRegistry {
   /**
    * Handle /info/{gem} endpoint (Compact Index)
    */
-  private async handleInfoFile(gemName: string): Promise<IResponse> {
-    const content = await this.storage.getRubyGemsInfo(gemName);
+  private async handleInfoFile(gemName: string, actor?: IRequestActor): Promise<IResponse> {
+    let content = await this.storage.getRubyGemsInfo(gemName);
+
+    // Try upstream if not found locally
+    if (!content) {
+      const upstream = await this.getUpstreamForRequest(gemName, 'info', 'GET', actor);
+      if (upstream) {
+        const upstreamInfo = await upstream.fetchInfo(gemName);
+        if (upstreamInfo) {
+          // Cache locally
+          await this.storage.putRubyGemsInfo(gemName, upstreamInfo);
+          content = upstreamInfo;
+        }
+      }
+    }
 
     if (!content) {
       return {
@@ -239,18 +297,42 @@ export class RubyGemsRegistry extends BaseRegistry {
   /**
    * Handle gem file download
    */
-  private async handleDownload(filename: string): Promise<IResponse> {
+  private async handleDownload(filename: string, actor?: IRequestActor): Promise<IResponse> {
     const parsed = helpers.parseGemFilename(filename);
     if (!parsed) {
       return this.errorResponse(400, 'Invalid gem filename');
     }
 
-    const gemData = await this.storage.getRubyGemsGem(
+    // Try streaming from local storage first
+    const streamResult = await this.storage.getRubyGemsGemStream(
       parsed.name,
       parsed.version,
       parsed.platform
     );
 
+    if (streamResult) {
+      return {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Disposition': `attachment; filename="${filename}"`,
+          'Content-Length': streamResult.size.toString()
+        },
+        body: streamResult.stream,
+      };
+    }
+
+    // Try upstream if not found locally
+    let gemData: Buffer | null = null;
+    const upstream = await this.getUpstreamForRequest(parsed.name, 'gem', 'GET', actor);
+    if (upstream) {
+      gemData = await upstream.fetchGem(parsed.name, parsed.version);
+      if (gemData) {
+        // Cache locally
+        await this.storage.putRubyGemsGem(parsed.name, parsed.version, gemData, parsed.platform);
+      }
+    }
+
     if (!gemData) {
       return this.errorResponse(404, 'Gem not found');
     }

ts/rubygems/classes.rubygemsupstream.ts

@@ -0,0 +1,230 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+
+/**
+ * RubyGems-specific upstream implementation.
+ *
+ * Handles:
+ * - Compact Index format (/versions, /info/{gem}, /names)
+ * - Gem file (.gem) downloading
+ * - Gem spec fetching
+ * - HTTP Range requests for incremental updates
+ */
+export class RubygemsUpstream extends BaseUpstream {
+  protected readonly protocolName = 'rubygems';
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+  }
+
+  /**
+   * Fetch the /versions file (master list of all gems).
+   */
+  public async fetchVersions(etag?: string): Promise<{ data: string; etag?: string } | null> {
+    const headers: Record<string, string> = {
+      'accept': 'text/plain',
+    };
+
+    if (etag) {
+      headers['if-none-match'] = etag;
+    }
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: '*',
+      resourceType: 'versions',
+      path: '/versions',
+      method: 'GET',
+      headers,
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    let data: string;
+    if (Buffer.isBuffer(result.body)) {
+      data = result.body.toString('utf8');
+    } else if (typeof result.body === 'string') {
+      data = result.body;
+    } else {
+      return null;
+    }
+
+    return {
+      data,
+      etag: result.headers['etag'],
+    };
+  }
+
+  /**
+   * Fetch gem info file (/info/{gemname}).
+   */
+  public async fetchInfo(gemName: string): Promise<string | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: gemName,
+      resourceType: 'info',
+      path: `/info/${gemName}`,
+      method: 'GET',
+      headers: {
+        'accept': 'text/plain',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch the /names file (list of all gem names).
+   */
+  public async fetchNames(): Promise<string | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: '*',
+      resourceType: 'names',
+      path: '/names',
+      method: 'GET',
+      headers: {
+        'accept': 'text/plain',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch a gem file.
+   */
+  public async fetchGem(gemName: string, version: string): Promise<Buffer | null> {
+    const path = `/gems/${gemName}-${version}.gem`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: gemName,
+      resourceType: 'gem',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Fetch gem spec (quick spec).
+   */
+  public async fetchQuickSpec(gemName: string, version: string): Promise<Buffer | null> {
+    const path = `/quick/Marshal.4.8/${gemName}-${version}.gemspec.rz`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: gemName,
+      resourceType: 'spec',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Fetch gem versions JSON from API.
+   */
+  public async fetchVersionsJson(gemName: string): Promise<any[] | null> {
+    const path = `/api/v1/versions/${gemName}.json`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'rubygems',
+      resource: gemName,
+      resourceType: 'versions-json',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/json',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return JSON.parse(result.body.toString('utf8'));
+    }
+
+    return Array.isArray(result.body) ? result.body : null;
+  }
+
+  /**
+   * Override URL building for RubyGems-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

ts/rubygems/helpers.rubygems.ts

@@ -427,7 +427,7 @@ export async function extractGemMetadata(gemData: Buffer): Promise<{
     // Step 2: Decompress the gzipped metadata
     const gzipTools = new plugins.smartarchive.GzipTools();
     const metadataYaml = await gzipTools.decompress(metadataFile.contentBuffer);
-    const yamlContent = metadataYaml.toString('utf-8');
+    const yamlContent = Buffer.from(metadataYaml).toString('utf-8');
 
     // Step 3: Parse the YAML to extract name, version, platform
     // Look for name: field in YAML
@@ -455,9 +455,8 @@ export async function extractGemMetadata(gemData: Buffer): Promise<{
     }
 
     return null;
-  } catch (error) {
-    // Log error for debugging but return null gracefully
-    console.error('Failed to extract gem metadata:', error);
+  } catch (_error) {
+    // Error handled gracefully - return null and let caller handle missing metadata
     return null;
   }
 }
@@ -504,7 +503,7 @@ export async function generateSpecsGz(specs: Array<[string, string, string]>): P
   }
 
   const uncompressed = Buffer.concat(parts);
-  return gzipTools.compress(uncompressed);
+  return Buffer.from(await gzipTools.compress(uncompressed));
 }
 
 /**

ts/rubygems/index.ts

@@ -5,4 +5,5 @@
 
 export * from './interfaces.rubygems.js';
 export * from './classes.rubygemsregistry.js';
+export { RubygemsUpstream } from './classes.rubygemsupstream.js';
 export * as rubygemsHelpers from './helpers.rubygems.js';

ts/upstream/classes.baseupstream.ts

@@ -0,0 +1,526 @@
+import * as plugins from '../plugins.js';
+import type {
+  IUpstreamRegistryConfig,
+  IUpstreamAuthConfig,
+  IUpstreamCacheConfig,
+  IUpstreamResilienceConfig,
+  IUpstreamResult,
+  IUpstreamFetchContext,
+  IProtocolUpstreamConfig,
+  IUpstreamScopeRule,
+  TCircuitState,
+} from './interfaces.upstream.js';
+import {
+  DEFAULT_CACHE_CONFIG,
+  DEFAULT_RESILIENCE_CONFIG,
+} from './interfaces.upstream.js';
+import { CircuitBreaker, CircuitOpenError, withCircuitBreaker } from './classes.circuitbreaker.js';
+import { UpstreamCache } from './classes.upstreamcache.js';
+
+/**
+ * Base class for protocol-specific upstream implementations.
+ *
+ * Provides:
+ * - Multi-upstream routing with priority
+ * - Scope-based filtering (glob patterns)
+ * - Authentication handling
+ * - Circuit breaker per upstream
+ * - Caching with TTL
+ * - Retry with exponential backoff
+ * - 429 rate limit handling
+ */
+export abstract class BaseUpstream {
+  /** Protocol name for logging */
+  protected abstract readonly protocolName: string;
+
+  /** Upstream configuration */
+  protected readonly config: IProtocolUpstreamConfig;
+
+  /** Resolved cache configuration */
+  protected readonly cacheConfig: IUpstreamCacheConfig;
+
+  /** Resolved resilience configuration */
+  protected readonly resilienceConfig: IUpstreamResilienceConfig;
+
+  /** Circuit breakers per upstream */
+  protected readonly circuitBreakers: Map<string, CircuitBreaker> = new Map();
+
+  /** Upstream cache */
+  protected readonly cache: UpstreamCache;
+
+  /** Logger instance */
+  protected readonly logger: plugins.smartlog.Smartlog;
+
+  constructor(config: IProtocolUpstreamConfig, logger?: plugins.smartlog.Smartlog) {
+    this.config = config;
+    this.cacheConfig = { ...DEFAULT_CACHE_CONFIG, ...config.cache };
+    this.resilienceConfig = { ...DEFAULT_RESILIENCE_CONFIG, ...config.resilience };
+    this.cache = new UpstreamCache(this.cacheConfig);
+    this.logger = logger || new plugins.smartlog.Smartlog({
+      logContext: {
+        company: 'smartregistry',
+        companyunit: 'upstream',
+        environment: 'production',
+        runtime: 'node',
+      }
+    });
+
+    // Initialize circuit breakers for each upstream
+    for (const upstream of config.upstreams) {
+      const upstreamResilience = { ...this.resilienceConfig, ...upstream.resilience };
+      this.circuitBreakers.set(upstream.id, new CircuitBreaker(upstream.id, upstreamResilience));
+    }
+  }
+
+  /**
+   * Check if upstream is enabled.
+   */
+  public isEnabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Get all configured upstreams.
+   */
+  public getUpstreams(): IUpstreamRegistryConfig[] {
+    return this.config.upstreams;
+  }
+
+  /**
+   * Get circuit breaker state for an upstream.
+   */
+  public getCircuitState(upstreamId: string): TCircuitState | null {
+    const breaker = this.circuitBreakers.get(upstreamId);
+    return breaker ? breaker.getState() : null;
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  public getCacheStats() {
+    return this.cache.getStats();
+  }
+
+  /**
+   * Fetch a resource from upstreams.
+   * Tries upstreams in priority order, respecting circuit breakers and scope rules.
+   */
+  public async fetch(context: IUpstreamFetchContext): Promise<IUpstreamResult | null> {
+    if (!this.config.enabled) {
+      return null;
+    }
+
+    // Get applicable upstreams sorted by priority
+    const applicableUpstreams = this.getApplicableUpstreams(context.resource);
+
+    if (applicableUpstreams.length === 0) {
+      return null;
+    }
+
+    // Use the first applicable upstream's URL for cache key
+    const primaryUpstreamUrl = applicableUpstreams[0]?.url;
+
+    // Check cache first
+    const cached = await this.cache.get(context, primaryUpstreamUrl);
+    if (cached && !cached.stale) {
+      return {
+        success: true,
+        status: 200,
+        headers: cached.headers,
+        body: cached.data,
+        upstreamId: cached.upstreamId,
+        fromCache: true,
+        latencyMs: 0,
+      };
+    }
+
+    // Check for negative cache (recent 404)
+    if (await this.cache.hasNegative(context, primaryUpstreamUrl)) {
+      return {
+        success: false,
+        status: 404,
+        headers: {},
+        upstreamId: 'cache',
+        fromCache: true,
+        latencyMs: 0,
+      };
+    }
+
+    // If we have stale cache, return it immediately and revalidate in background
+    if (cached?.stale && this.cacheConfig.staleWhileRevalidate) {
+      // Fire and forget revalidation
+      this.revalidateInBackground(context, applicableUpstreams);
+      return {
+        success: true,
+        status: 200,
+        headers: cached.headers,
+        body: cached.data,
+        upstreamId: cached.upstreamId,
+        fromCache: true,
+        latencyMs: 0,
+      };
+    }
+
+    // Try each upstream in order
+    let lastError: Error | null = null;
+
+    for (const upstream of applicableUpstreams) {
+      const breaker = this.circuitBreakers.get(upstream.id);
+      if (!breaker) continue;
+
+      try {
+        const result = await withCircuitBreaker(
+          breaker,
+          () => this.fetchFromUpstream(upstream, context),
+        );
+
+        // Cache successful responses
+        if (result.success && result.body) {
+          await this.cache.set(
+            context,
+            Buffer.isBuffer(result.body) ? result.body : Buffer.from(JSON.stringify(result.body)),
+            result.headers['content-type'] || 'application/octet-stream',
+            result.headers,
+            upstream.id,
+            upstream.url,
+          );
+        }
+
+        // Cache 404 responses
+        if (result.status === 404) {
+          await this.cache.setNegative(context, upstream.id, upstream.url);
+        }
+
+        return result;
+      } catch (error) {
+        if (error instanceof CircuitOpenError) {
+          this.logger.log('debug', `Circuit open for upstream ${upstream.id}, trying next`);
+        } else {
+          this.logger.log('warn', `Upstream ${upstream.id} failed: ${(error as Error).message}`);
+        }
+        lastError = error as Error;
+        // Continue to next upstream
+      }
+    }
+
+    // All upstreams failed
+    if (lastError) {
+      this.logger.log('error', `All upstreams failed for ${context.resource}: ${lastError.message}`);
+    }
+
+    return null;
+  }
+
+  /**
+   * Invalidate cache for a resource pattern.
+   */
+  public async invalidateCache(pattern: RegExp): Promise<number> {
+    return this.cache.invalidatePattern(pattern);
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  public async clearCache(): Promise<void> {
+    await this.cache.clear();
+  }
+
+  /**
+   * Stop the upstream (cleanup resources).
+   */
+  public stop(): void {
+    this.cache.stop();
+  }
+
+  /**
+   * Get upstreams that apply to a resource, sorted by priority.
+   */
+  protected getApplicableUpstreams(resource: string): IUpstreamRegistryConfig[] {
+    return this.config.upstreams
+      .filter(upstream => {
+        if (!upstream.enabled) return false;
+
+        // Check circuit breaker
+        const breaker = this.circuitBreakers.get(upstream.id);
+        if (breaker && !breaker.canRequest()) return false;
+
+        // Check scope rules
+        return this.matchesScopeRules(resource, upstream.scopeRules);
+      })
+      .sort((a, b) => a.priority - b.priority);
+  }
+
+  /**
+   * Check if a resource matches scope rules.
+   * Empty rules = match all.
+   */
+  protected matchesScopeRules(resource: string, rules?: IUpstreamScopeRule[]): boolean {
+    if (!rules || rules.length === 0) {
+      return true;
+    }
+
+    // Process rules in order
+    // Start with default exclude (nothing matches)
+    let matched = false;
+
+    for (const rule of rules) {
+      const isMatch = plugins.minimatch(resource, rule.pattern);
+      if (isMatch) {
+        matched = rule.action === 'include';
+      }
+    }
+
+    return matched;
+  }
+
+  /**
+   * Fetch from a specific upstream with retry logic.
+   */
+  protected async fetchFromUpstream(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): Promise<IUpstreamResult> {
+    const upstreamResilience = { ...this.resilienceConfig, ...upstream.resilience };
+    const startTime = Date.now();
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= upstreamResilience.maxRetries; attempt++) {
+      try {
+        const result = await this.executeRequest(upstream, context, upstreamResilience.timeoutMs);
+        return {
+          ...result,
+          upstreamId: upstream.id,
+          fromCache: false,
+          latencyMs: Date.now() - startTime,
+        };
+      } catch (error) {
+        lastError = error as Error;
+
+        // Don't retry on 4xx errors (except 429)
+        if (this.isNonRetryableError(error)) {
+          break;
+        }
+
+        // Calculate delay with exponential backoff and jitter
+        if (attempt < upstreamResilience.maxRetries) {
+          const delay = this.calculateBackoffDelay(
+            attempt,
+            upstreamResilience.retryDelayMs,
+            upstreamResilience.retryMaxDelayMs,
+          );
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Request failed');
+  }
+
+  /**
+   * Execute a single HTTP request to an upstream.
+   */
+  protected async executeRequest(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+    timeoutMs: number,
+  ): Promise<Omit<IUpstreamResult, 'upstreamId' | 'fromCache' | 'latencyMs'>> {
+    // Build the full URL
+    const url = this.buildUpstreamUrl(upstream, context);
+
+    // Build headers with auth
+    const headers = this.buildHeaders(upstream, context);
+
+    // Make the request using SmartRequest
+    const request = plugins.smartrequest.SmartRequest.create()
+      .url(url)
+      .method(context.method as any)
+      .headers(headers)
+      .timeout(timeoutMs)
+      .handle429Backoff({ maxRetries: 3, fallbackDelay: 1000, maxWaitTime: 30000 });
+
+    // Add query params if present
+    if (Object.keys(context.query).length > 0) {
+      request.query(context.query);
+    }
+
+    let response: plugins.smartrequest.ICoreResponse;
+
+    switch (context.method.toUpperCase()) {
+      case 'GET':
+        response = await request.get();
+        break;
+      case 'HEAD':
+        // SmartRequest doesn't have head(), use options
+        response = await request.method('HEAD').get();
+        break;
+      default:
+        response = await request.get();
+    }
+
+    // Parse response
+    const responseHeaders: Record<string, string> = {};
+    for (const [key, value] of Object.entries(response.headers)) {
+      responseHeaders[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+    }
+
+    let body: Buffer | any;
+    const contentType = responseHeaders['content-type'] || '';
+
+    if (response.ok) {
+      if (contentType.includes('application/json')) {
+        body = await response.json();
+      } else {
+        const arrayBuffer = await response.arrayBuffer();
+        body = Buffer.from(arrayBuffer);
+      }
+    }
+
+    return {
+      success: response.ok,
+      status: response.status,
+      headers: responseHeaders,
+      body,
+    };
+  }
+
+  /**
+   * Build the full URL for an upstream request.
+   * Subclasses can override for protocol-specific URL building.
+   */
+  protected buildUpstreamUrl(upstream: IUpstreamRegistryConfig, context: IUpstreamFetchContext): string {
+    // Remove leading slash if URL already has trailing slash
+    let path = context.path;
+    if (upstream.url.endsWith('/') && path.startsWith('/')) {
+      path = path.slice(1);
+    }
+    return `${upstream.url}${path}`;
+  }
+
+  /**
+   * Build headers including authentication.
+   */
+  protected buildHeaders(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): Record<string, string> {
+    const headers: Record<string, string> = { ...context.headers };
+
+    // Remove host header (will be set by HTTP client)
+    delete headers['host'];
+
+    // Add authentication
+    this.addAuthHeaders(headers, upstream.auth);
+
+    return headers;
+  }
+
+  /**
+   * Add authentication headers based on auth config.
+   */
+  protected addAuthHeaders(headers: Record<string, string>, auth: IUpstreamAuthConfig): void {
+    switch (auth.type) {
+      case 'basic':
+        if (auth.username && auth.password) {
+          const credentials = Buffer.from(`${auth.username}:${auth.password}`).toString('base64');
+          headers['authorization'] = `Basic ${credentials}`;
+        }
+        break;
+      case 'bearer':
+        if (auth.token) {
+          headers['authorization'] = `Bearer ${auth.token}`;
+        }
+        break;
+      case 'api-key':
+        if (auth.token) {
+          const headerName = auth.headerName || 'authorization';
+          headers[headerName.toLowerCase()] = auth.token;
+        }
+        break;
+      case 'none':
+      default:
+        // No authentication
+        break;
+    }
+  }
+
+  /**
+   * Check if an error should not be retried.
+   */
+  protected isNonRetryableError(error: unknown): boolean {
+    // Check for HTTP status errors
+    if (error && typeof error === 'object' && 'status' in error) {
+      const status = (error as { status: number }).status;
+      // Don't retry 4xx errors except 429 (rate limited)
+      if (status >= 400 && status < 500 && status !== 429) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Calculate backoff delay with exponential backoff and jitter.
+   */
+  protected calculateBackoffDelay(
+    attempt: number,
+    baseDelayMs: number,
+    maxDelayMs: number,
+  ): number {
+    // Exponential backoff: delay = base * 2^attempt
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+
+    // Cap at max delay
+    const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+
+    // Add jitter (±25%)
+    const jitter = cappedDelay * 0.25 * (Math.random() * 2 - 1);
+
+    return Math.floor(cappedDelay + jitter);
+  }
+
+  /**
+   * Sleep for a specified duration.
+   */
+  protected sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Revalidate cache in background.
+   */
+  protected async revalidateInBackground(
+    context: IUpstreamFetchContext,
+    upstreams: IUpstreamRegistryConfig[],
+  ): Promise<void> {
+    try {
+      for (const upstream of upstreams) {
+        const breaker = this.circuitBreakers.get(upstream.id);
+        if (!breaker || !breaker.canRequest()) continue;
+
+        try {
+          const result = await withCircuitBreaker(
+            breaker,
+            () => this.fetchFromUpstream(upstream, context),
+          );
+
+          if (result.success && result.body) {
+            await this.cache.set(
+              context,
+              Buffer.isBuffer(result.body) ? result.body : Buffer.from(JSON.stringify(result.body)),
+              result.headers['content-type'] || 'application/octet-stream',
+              result.headers,
+              upstream.id,
+              upstream.url,
+            );
+            return; // Successfully revalidated
+          }
+        } catch {
+          // Continue to next upstream
+        }
+      }
+    } catch (error) {
+      this.logger.log('debug', `Background revalidation failed: ${(error as Error).message}`);
+    }
+  }
+}

ts/upstream/classes.circuitbreaker.ts

@@ -0,0 +1,238 @@
+import type { TCircuitState, IUpstreamResilienceConfig } from './interfaces.upstream.js';
+import { DEFAULT_RESILIENCE_CONFIG } from './interfaces.upstream.js';
+
+/**
+ * Circuit breaker implementation for upstream resilience.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit is tripped, requests fail fast
+ * - HALF_OPEN: Testing if upstream has recovered
+ *
+ * Transitions:
+ * - CLOSED → OPEN: When failure count exceeds threshold
+ * - OPEN → HALF_OPEN: After reset timeout expires
+ * - HALF_OPEN → CLOSED: On successful request
+ * - HALF_OPEN → OPEN: On failed request
+ */
+export class CircuitBreaker {
+  /** Unique identifier for logging and metrics */
+  public readonly id: string;
+
+  /** Current circuit state */
+  private state: TCircuitState = 'CLOSED';
+
+  /** Count of consecutive failures */
+  private failureCount: number = 0;
+
+  /** Timestamp when circuit was opened */
+  private openedAt: number = 0;
+
+  /** Number of successful requests in half-open state */
+  private halfOpenSuccesses: number = 0;
+
+  /** Configuration */
+  private readonly config: IUpstreamResilienceConfig;
+
+  /** Number of successes required to close circuit from half-open */
+  private readonly halfOpenThreshold: number = 2;
+
+  constructor(id: string, config?: Partial<IUpstreamResilienceConfig>) {
+    this.id = id;
+    this.config = { ...DEFAULT_RESILIENCE_CONFIG, ...config };
+  }
+
+  /**
+   * Get current circuit state.
+   */
+  public getState(): TCircuitState {
+    // Check if we should transition from OPEN to HALF_OPEN
+    if (this.state === 'OPEN') {
+      const elapsed = Date.now() - this.openedAt;
+      if (elapsed >= this.config.circuitBreakerResetMs) {
+        this.transitionTo('HALF_OPEN');
+      }
+    }
+    return this.state;
+  }
+
+  /**
+   * Check if circuit allows requests.
+   * Returns true if requests should be allowed.
+   */
+  public canRequest(): boolean {
+    const currentState = this.getState();
+    return currentState !== 'OPEN';
+  }
+
+  /**
+   * Record a successful request.
+   * May transition circuit from HALF_OPEN to CLOSED.
+   */
+  public recordSuccess(): void {
+    if (this.state === 'HALF_OPEN') {
+      this.halfOpenSuccesses++;
+      if (this.halfOpenSuccesses >= this.halfOpenThreshold) {
+        this.transitionTo('CLOSED');
+      }
+    } else if (this.state === 'CLOSED') {
+      // Reset failure count on success
+      this.failureCount = 0;
+    }
+  }
+
+  /**
+   * Record a failed request.
+   * May transition circuit from CLOSED/HALF_OPEN to OPEN.
+   */
+  public recordFailure(): void {
+    if (this.state === 'HALF_OPEN') {
+      // Any failure in half-open immediately opens circuit
+      this.transitionTo('OPEN');
+    } else if (this.state === 'CLOSED') {
+      this.failureCount++;
+      if (this.failureCount >= this.config.circuitBreakerThreshold) {
+        this.transitionTo('OPEN');
+      }
+    }
+  }
+
+  /**
+   * Force circuit to open state.
+   * Useful for manual intervention or external health checks.
+   */
+  public forceOpen(): void {
+    this.transitionTo('OPEN');
+  }
+
+  /**
+   * Force circuit to closed state.
+   * Useful for manual intervention after fixing upstream issues.
+   */
+  public forceClose(): void {
+    this.transitionTo('CLOSED');
+  }
+
+  /**
+   * Reset circuit to initial state.
+   */
+  public reset(): void {
+    this.state = 'CLOSED';
+    this.failureCount = 0;
+    this.openedAt = 0;
+    this.halfOpenSuccesses = 0;
+  }
+
+  /**
+   * Get circuit metrics for monitoring.
+   */
+  public getMetrics(): ICircuitBreakerMetrics {
+    return {
+      id: this.id,
+      state: this.getState(),
+      failureCount: this.failureCount,
+      openedAt: this.openedAt > 0 ? new Date(this.openedAt) : null,
+      timeUntilHalfOpen: this.state === 'OPEN'
+        ? Math.max(0, this.config.circuitBreakerResetMs - (Date.now() - this.openedAt))
+        : 0,
+      halfOpenSuccesses: this.halfOpenSuccesses,
+      threshold: this.config.circuitBreakerThreshold,
+      resetMs: this.config.circuitBreakerResetMs,
+    };
+  }
+
+  /**
+   * Transition to a new state with proper cleanup.
+   */
+  private transitionTo(newState: TCircuitState): void {
+    const previousState = this.state;
+    this.state = newState;
+
+    switch (newState) {
+      case 'OPEN':
+        this.openedAt = Date.now();
+        this.halfOpenSuccesses = 0;
+        break;
+      case 'HALF_OPEN':
+        this.halfOpenSuccesses = 0;
+        break;
+      case 'CLOSED':
+        this.failureCount = 0;
+        this.openedAt = 0;
+        this.halfOpenSuccesses = 0;
+        break;
+    }
+
+    // Log state transition (useful for debugging and monitoring)
+    // In production, this would emit events or metrics
+    if (previousState !== newState) {
+      // State changed - could emit event here
+    }
+  }
+}
+
+/**
+ * Metrics for circuit breaker monitoring.
+ */
+export interface ICircuitBreakerMetrics {
+  /** Circuit breaker identifier */
+  id: string;
+  /** Current state */
+  state: TCircuitState;
+  /** Number of consecutive failures */
+  failureCount: number;
+  /** When circuit was opened (null if never opened) */
+  openedAt: Date | null;
+  /** Milliseconds until circuit transitions to half-open (0 if not open) */
+  timeUntilHalfOpen: number;
+  /** Number of successes in half-open state */
+  halfOpenSuccesses: number;
+  /** Failure threshold for opening circuit */
+  threshold: number;
+  /** Reset timeout in milliseconds */
+  resetMs: number;
+}
+
+/**
+ * Execute a function with circuit breaker protection.
+ *
+ * @param breaker The circuit breaker to use
+ * @param fn The async function to execute
+ * @param fallback Optional fallback function when circuit is open
+ * @returns The result of fn or fallback
+ * @throws CircuitOpenError if circuit is open and no fallback provided
+ */
+export async function withCircuitBreaker<T>(
+  breaker: CircuitBreaker,
+  fn: () => Promise<T>,
+  fallback?: () => Promise<T>,
+): Promise<T> {
+  if (!breaker.canRequest()) {
+    if (fallback) {
+      return fallback();
+    }
+    throw new CircuitOpenError(breaker.id);
+  }
+
+  try {
+    const result = await fn();
+    breaker.recordSuccess();
+    return result;
+  } catch (error) {
+    breaker.recordFailure();
+    throw error;
+  }
+}
+
+/**
+ * Error thrown when circuit is open and no fallback is provided.
+ */
+export class CircuitOpenError extends Error {
+  public readonly circuitId: string;
+
+  constructor(circuitId: string) {
+    super(`Circuit breaker '${circuitId}' is open`);
+    this.name = 'CircuitOpenError';
+    this.circuitId = circuitId;
+  }
+}

ts/upstream/classes.upstreamcache.ts

@@ -0,0 +1,626 @@
+import type {
+  ICacheEntry,
+  IUpstreamCacheConfig,
+  IUpstreamFetchContext,
+} from './interfaces.upstream.js';
+import { DEFAULT_CACHE_CONFIG } from './interfaces.upstream.js';
+import type { IStorageBackend } from '../core/interfaces.core.js';
+
+/**
+ * Cache metadata stored alongside cache entries.
+ */
+interface ICacheMetadata {
+  contentType: string;
+  headers: Record<string, string>;
+  cachedAt: string;
+  expiresAt?: string;
+  etag?: string;
+  upstreamId: string;
+  upstreamUrl: string;
+}
+
+/**
+ * S3-backed upstream cache with in-memory hot layer.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - Stale-while-revalidate support
+ * - Negative caching (404s)
+ * - Content-type aware caching
+ * - ETag support for conditional requests
+ * - Multi-upstream support via URL-based cache paths
+ * - Persistent S3 storage with in-memory hot layer
+ *
+ * Cache paths are structured as:
+ *   cache/{escaped-upstream-url}/{protocol}:{method}:{path}
+ *
+ * @example
+ * ```typescript
+ * // In-memory only (default)
+ * const cache = new UpstreamCache(config);
+ *
+ * // With S3 persistence
+ * const cache = new UpstreamCache(config, 10000, storage);
+ * ```
+ */
+export class UpstreamCache {
+  /** In-memory hot cache */
+  private readonly memoryCache: Map<string, ICacheEntry> = new Map();
+
+  /** Configuration */
+  private readonly config: IUpstreamCacheConfig;
+
+  /** Maximum in-memory cache entries */
+  private readonly maxMemoryEntries: number;
+
+  /** S3 storage backend (optional) */
+  private readonly storage?: IStorageBackend;
+
+  /** Cleanup interval handle */
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    config?: Partial<IUpstreamCacheConfig>,
+    maxMemoryEntries: number = 10000,
+    storage?: IStorageBackend
+  ) {
+    this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
+    this.maxMemoryEntries = maxMemoryEntries;
+    this.storage = storage;
+
+    // Start periodic cleanup if caching is enabled
+    if (this.config.enabled) {
+      this.startCleanup();
+    }
+  }
+
+  /**
+   * Check if caching is enabled.
+   */
+  public isEnabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Check if S3 storage is configured.
+   */
+  public hasStorage(): boolean {
+    return !!this.storage;
+  }
+
+  /**
+   * Get cached entry for a request context.
+   * Checks memory first, then falls back to S3.
+   * Returns null if not found or expired (unless stale-while-revalidate).
+   */
+  public async get(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<ICacheEntry | null> {
+    if (!this.config.enabled) {
+      return null;
+    }
+
+    const key = this.buildCacheKey(context, upstreamUrl);
+
+    // Check memory cache first
+    let entry = this.memoryCache.get(key);
+
+    // If not in memory and we have storage, check S3
+    if (!entry && this.storage) {
+      entry = (await this.loadFromStorage(key)) ?? undefined;
+      if (entry) {
+        // Promote to memory cache
+        this.memoryCache.set(key, entry);
+      }
+    }
+
+    if (!entry) {
+      return null;
+    }
+
+    const now = new Date();
+
+    // Check if entry is expired
+    if (entry.expiresAt && entry.expiresAt < now) {
+      // Check if we can serve stale content
+      if (this.config.staleWhileRevalidate && !entry.stale) {
+        const staleAge = (now.getTime() - entry.expiresAt.getTime()) / 1000;
+        if (staleAge <= this.config.staleMaxAgeSeconds) {
+          // Mark as stale and return
+          entry.stale = true;
+          return entry;
+        }
+      }
+      // Entry is too old, remove it
+      this.memoryCache.delete(key);
+      if (this.storage) {
+        await this.deleteFromStorage(key).catch(() => {});
+      }
+      return null;
+    }
+
+    return entry;
+  }
+
+  /**
+   * Store a response in the cache (memory and optionally S3).
+   */
+  public async set(
+    context: IUpstreamFetchContext,
+    data: Buffer,
+    contentType: string,
+    headers: Record<string, string>,
+    upstreamId: string,
+    upstreamUrl: string,
+    options?: ICacheSetOptions,
+  ): Promise<void> {
+    if (!this.config.enabled) {
+      return;
+    }
+
+    // Enforce max memory entries limit
+    if (this.memoryCache.size >= this.maxMemoryEntries) {
+      this.evictOldest();
+    }
+
+    const key = this.buildCacheKey(context, upstreamUrl);
+    const now = new Date();
+
+    // Determine TTL based on content type
+    const ttlSeconds = options?.ttlSeconds ?? this.determineTtl(context, contentType, headers);
+
+    const entry: ICacheEntry = {
+      data,
+      contentType,
+      headers,
+      cachedAt: now,
+      expiresAt: ttlSeconds > 0 ? new Date(now.getTime() + ttlSeconds * 1000) : undefined,
+      etag: headers['etag'] || options?.etag,
+      upstreamId,
+      stale: false,
+    };
+
+    // Store in memory
+    this.memoryCache.set(key, entry);
+
+    // Store in S3 if available
+    if (this.storage) {
+      await this.saveToStorage(key, entry, upstreamUrl).catch(() => {});
+    }
+  }
+
+  /**
+   * Store a negative cache entry (404 response).
+   */
+  public async setNegative(context: IUpstreamFetchContext, upstreamId: string, upstreamUrl: string): Promise<void> {
+    if (!this.config.enabled || this.config.negativeCacheTtlSeconds <= 0) {
+      return;
+    }
+
+    const key = this.buildCacheKey(context, upstreamUrl);
+    const now = new Date();
+
+    const entry: ICacheEntry = {
+      data: Buffer.from(''),
+      contentType: 'application/octet-stream',
+      headers: {},
+      cachedAt: now,
+      expiresAt: new Date(now.getTime() + this.config.negativeCacheTtlSeconds * 1000),
+      upstreamId,
+      stale: false,
+    };
+
+    this.memoryCache.set(key, entry);
+
+    if (this.storage) {
+      await this.saveToStorage(key, entry, upstreamUrl).catch(() => {});
+    }
+  }
+
+  /**
+   * Check if there's a negative cache entry for this context.
+   */
+  public async hasNegative(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<boolean> {
+    const entry = await this.get(context, upstreamUrl);
+    return entry !== null && entry.data.length === 0;
+  }
+
+  /**
+   * Invalidate a specific cache entry.
+   */
+  public async invalidate(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<boolean> {
+    const key = this.buildCacheKey(context, upstreamUrl);
+    const deleted = this.memoryCache.delete(key);
+
+    if (this.storage) {
+      await this.deleteFromStorage(key).catch(() => {});
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Invalidate all entries matching a pattern.
+   * Useful for invalidating all versions of a package.
+   */
+  public async invalidatePattern(pattern: RegExp): Promise<number> {
+    let count = 0;
+    for (const key of this.memoryCache.keys()) {
+      if (pattern.test(key)) {
+        this.memoryCache.delete(key);
+        if (this.storage) {
+          await this.deleteFromStorage(key).catch(() => {});
+        }
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Invalidate all entries from a specific upstream.
+   */
+  public async invalidateUpstream(upstreamId: string): Promise<number> {
+    let count = 0;
+    for (const [key, entry] of this.memoryCache.entries()) {
+      if (entry.upstreamId === upstreamId) {
+        this.memoryCache.delete(key);
+        if (this.storage) {
+          await this.deleteFromStorage(key).catch(() => {});
+        }
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Clear all cache entries (memory and S3).
+   */
+  public async clear(): Promise<void> {
+    this.memoryCache.clear();
+
+    // Note: S3 cleanup would require listing and deleting all cache/* objects
+    // This is left as a future enhancement for bulk cleanup
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  public getStats(): ICacheStats {
+    let freshCount = 0;
+    let staleCount = 0;
+    let negativeCount = 0;
+    let totalSize = 0;
+    const now = new Date();
+
+    for (const entry of this.memoryCache.values()) {
+      totalSize += entry.data.length;
+
+      if (entry.data.length === 0) {
+        negativeCount++;
+      } else if (entry.stale || (entry.expiresAt && entry.expiresAt < now)) {
+        staleCount++;
+      } else {
+        freshCount++;
+      }
+    }
+
+    return {
+      totalEntries: this.memoryCache.size,
+      freshEntries: freshCount,
+      staleEntries: staleCount,
+      negativeEntries: negativeCount,
+      totalSizeBytes: totalSize,
+      maxEntries: this.maxMemoryEntries,
+      enabled: this.config.enabled,
+      hasStorage: !!this.storage,
+    };
+  }
+
+  /**
+   * Stop the cache and cleanup.
+   */
+  public stop(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  // ========================================================================
+  // Storage Methods
+  // ========================================================================
+
+  /**
+   * Build storage path for a cache key.
+   * Escapes upstream URL for safe use in S3 paths.
+   */
+  private buildStoragePath(key: string): string {
+    return `cache/${key}`;
+  }
+
+  /**
+   * Build storage path for cache metadata.
+   */
+  private buildMetadataPath(key: string): string {
+    return `cache/${key}.meta`;
+  }
+
+  /**
+   * Load a cache entry from S3 storage.
+   */
+  private async loadFromStorage(key: string): Promise<ICacheEntry | null> {
+    if (!this.storage) return null;
+
+    try {
+      const dataPath = this.buildStoragePath(key);
+      const metaPath = this.buildMetadataPath(key);
+
+      // Load data and metadata in parallel
+      const [data, metaBuffer] = await Promise.all([
+        this.storage.getObject(dataPath),
+        this.storage.getObject(metaPath),
+      ]);
+
+      if (!data || !metaBuffer) {
+        return null;
+      }
+
+      const meta: ICacheMetadata = JSON.parse(metaBuffer.toString('utf-8'));
+
+      return {
+        data,
+        contentType: meta.contentType,
+        headers: meta.headers,
+        cachedAt: new Date(meta.cachedAt),
+        expiresAt: meta.expiresAt ? new Date(meta.expiresAt) : undefined,
+        etag: meta.etag,
+        upstreamId: meta.upstreamId,
+        stale: false,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save a cache entry to S3 storage.
+   */
+  private async saveToStorage(key: string, entry: ICacheEntry, upstreamUrl: string): Promise<void> {
+    if (!this.storage) return;
+
+    const dataPath = this.buildStoragePath(key);
+    const metaPath = this.buildMetadataPath(key);
+
+    const meta: ICacheMetadata = {
+      contentType: entry.contentType,
+      headers: entry.headers,
+      cachedAt: entry.cachedAt.toISOString(),
+      expiresAt: entry.expiresAt?.toISOString(),
+      etag: entry.etag,
+      upstreamId: entry.upstreamId,
+      upstreamUrl,
+    };
+
+    // Save data and metadata in parallel
+    await Promise.all([
+      this.storage.putObject(dataPath, entry.data),
+      this.storage.putObject(metaPath, Buffer.from(JSON.stringify(meta), 'utf-8')),
+    ]);
+  }
+
+  /**
+   * Delete a cache entry from S3 storage.
+   */
+  private async deleteFromStorage(key: string): Promise<void> {
+    if (!this.storage) return;
+
+    const dataPath = this.buildStoragePath(key);
+    const metaPath = this.buildMetadataPath(key);
+
+    await Promise.all([
+      this.storage.deleteObject(dataPath).catch(() => {}),
+      this.storage.deleteObject(metaPath).catch(() => {}),
+    ]);
+  }
+
+  // ========================================================================
+  // Helper Methods
+  // ========================================================================
+
+  /**
+   * Escape a URL for safe use in storage paths.
+   */
+  private escapeUrl(url: string): string {
+    // Remove protocol prefix and escape special characters
+    return url
+      .replace(/^https?:\/\//, '')
+      .replace(/[\/\\:*?"<>|]/g, '_')
+      .replace(/__+/g, '_');
+  }
+
+  /**
+   * Build a unique cache key for a request context.
+   * Includes escaped upstream URL for multi-upstream support.
+   */
+  private buildCacheKey(context: IUpstreamFetchContext, upstreamUrl?: string): string {
+    // Include method, protocol, path, and sorted query params
+    const queryString = Object.keys(context.query)
+      .sort()
+      .map(k => `${k}=${context.query[k]}`)
+      .join('&');
+
+    const baseKey = `${context.protocol}:${context.method}:${context.path}${queryString ? '?' + queryString : ''}`;
+
+    if (upstreamUrl) {
+      return `${this.escapeUrl(upstreamUrl)}/${baseKey}`;
+    }
+
+    return baseKey;
+  }
+
+  /**
+   * Determine TTL based on content characteristics.
+   */
+  private determineTtl(
+    context: IUpstreamFetchContext,
+    contentType: string,
+    headers: Record<string, string>,
+  ): number {
+    // Check for Cache-Control header
+    const cacheControl = headers['cache-control'];
+    if (cacheControl) {
+      const maxAgeMatch = cacheControl.match(/max-age=(\d+)/);
+      if (maxAgeMatch) {
+        return parseInt(maxAgeMatch[1], 10);
+      }
+      if (cacheControl.includes('no-store') || cacheControl.includes('no-cache')) {
+        return 0;
+      }
+    }
+
+    // Check if content is immutable (content-addressable)
+    if (this.isImmutableContent(context, contentType)) {
+      return this.config.immutableTtlSeconds;
+    }
+
+    // Default TTL for mutable content
+    return this.config.defaultTtlSeconds;
+  }
+
+  /**
+   * Check if content is immutable (content-addressable).
+   */
+  private isImmutableContent(context: IUpstreamFetchContext, contentType: string): boolean {
+    // OCI blobs with digest are immutable
+    if (context.protocol === 'oci' && context.resourceType === 'blob') {
+      return true;
+    }
+
+    // NPM tarballs are immutable (versioned)
+    if (context.protocol === 'npm' && context.resourceType === 'tarball') {
+      return true;
+    }
+
+    // Maven artifacts with version are immutable
+    if (context.protocol === 'maven' && context.resourceType === 'artifact') {
+      return true;
+    }
+
+    // Cargo crate files are immutable
+    if (context.protocol === 'cargo' && context.resourceType === 'crate') {
+      return true;
+    }
+
+    // Composer dist files are immutable
+    if (context.protocol === 'composer' && context.resourceType === 'dist') {
+      return true;
+    }
+
+    // PyPI package files are immutable
+    if (context.protocol === 'pypi' && context.resourceType === 'package') {
+      return true;
+    }
+
+    // RubyGems .gem files are immutable
+    if (context.protocol === 'rubygems' && context.resourceType === 'gem') {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Evict oldest entries to make room for new ones.
+   */
+  private evictOldest(): void {
+    // Evict 10% of max entries
+    const evictCount = Math.ceil(this.maxMemoryEntries * 0.1);
+    let evicted = 0;
+
+    // First, try to evict stale entries
+    const now = new Date();
+    for (const [key, entry] of this.memoryCache.entries()) {
+      if (evicted >= evictCount) break;
+      if (entry.stale || (entry.expiresAt && entry.expiresAt < now)) {
+        this.memoryCache.delete(key);
+        evicted++;
+      }
+    }
+
+    // If not enough evicted, evict oldest by cachedAt
+    if (evicted < evictCount) {
+      const entries = Array.from(this.memoryCache.entries())
+        .sort((a, b) => a[1].cachedAt.getTime() - b[1].cachedAt.getTime());
+
+      for (const [key] of entries) {
+        if (evicted >= evictCount) break;
+        this.memoryCache.delete(key);
+        evicted++;
+      }
+    }
+  }
+
+  /**
+   * Start periodic cleanup of expired entries.
+   */
+  private startCleanup(): void {
+    // Run cleanup every minute
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, 60000);
+
+    // Don't keep the process alive just for cleanup
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  /**
+   * Remove all expired entries from memory cache.
+   */
+  private cleanup(): void {
+    const now = new Date();
+    const staleDeadline = new Date(now.getTime() - this.config.staleMaxAgeSeconds * 1000);
+
+    for (const [key, entry] of this.memoryCache.entries()) {
+      if (entry.expiresAt) {
+        // Remove if past stale deadline
+        if (entry.expiresAt < staleDeadline) {
+          this.memoryCache.delete(key);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Options for cache set operation.
+ */
+export interface ICacheSetOptions {
+  /** Override TTL in seconds */
+  ttlSeconds?: number;
+  /** ETag for conditional requests */
+  etag?: string;
+}
+
+/**
+ * Cache statistics.
+ */
+export interface ICacheStats {
+  /** Total number of cached entries in memory */
+  totalEntries: number;
+  /** Number of fresh (non-expired) entries */
+  freshEntries: number;
+  /** Number of stale entries (expired but still usable) */
+  staleEntries: number;
+  /** Number of negative cache entries */
+  negativeEntries: number;
+  /** Total size of cached data in bytes (memory only) */
+  totalSizeBytes: number;
+  /** Maximum allowed memory entries */
+  maxEntries: number;
+  /** Whether caching is enabled */
+  enabled: boolean;
+  /** Whether S3 storage is configured */
+  hasStorage: boolean;
+}

ts/upstream/index.ts

@@ -0,0 +1,11 @@
+// Interfaces and types
+export * from './interfaces.upstream.js';
+
+// Classes
+export { CircuitBreaker, CircuitOpenError, withCircuitBreaker } from './classes.circuitbreaker.js';
+export type { ICircuitBreakerMetrics } from './classes.circuitbreaker.js';
+
+export { UpstreamCache } from './classes.upstreamcache.js';
+export type { ICacheSetOptions, ICacheStats } from './classes.upstreamcache.js';
+
+export { BaseUpstream } from './classes.baseupstream.js';

ts/upstream/interfaces.upstream.ts

@@ -0,0 +1,276 @@
+import type { TRegistryProtocol, IRequestActor } from '../core/interfaces.core.js';
+
+/**
+ * Scope rule for routing requests to specific upstreams.
+ * Uses glob patterns for flexible matching.
+ */
+export interface IUpstreamScopeRule {
+  /** Glob pattern (e.g., "@company/*", "com.example.*", "library/*") */
+  pattern: string;
+  /** Whether matching resources should be included or excluded */
+  action: 'include' | 'exclude';
+}
+
+/**
+ * Authentication configuration for an upstream registry.
+ * Supports multiple auth strategies.
+ */
+export interface IUpstreamAuthConfig {
+  /** Authentication type */
+  type: 'none' | 'basic' | 'bearer' | 'api-key';
+  /** Username for basic auth */
+  username?: string;
+  /** Password for basic auth */
+  password?: string;
+  /** Token for bearer or api-key auth */
+  token?: string;
+  /** Custom header name for api-key auth (default: 'Authorization') */
+  headerName?: string;
+}
+
+/**
+ * Cache configuration for upstream content.
+ */
+export interface IUpstreamCacheConfig {
+  /** Whether caching is enabled */
+  enabled: boolean;
+  /** Default TTL in seconds for mutable content (default: 300 = 5 min) */
+  defaultTtlSeconds: number;
+  /** TTL in seconds for immutable/content-addressable content (default: 2592000 = 30 days) */
+  immutableTtlSeconds: number;
+  /** Whether to serve stale content while revalidating in background */
+  staleWhileRevalidate: boolean;
+  /** Maximum age in seconds for stale content (default: 3600 = 1 hour) */
+  staleMaxAgeSeconds: number;
+  /** TTL in seconds for negative cache entries (404s) (default: 60 = 1 min) */
+  negativeCacheTtlSeconds: number;
+}
+
+/**
+ * Resilience configuration for upstream requests.
+ */
+export interface IUpstreamResilienceConfig {
+  /** Request timeout in milliseconds (default: 30000) */
+  timeoutMs: number;
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries: number;
+  /** Initial retry delay in milliseconds (default: 1000) */
+  retryDelayMs: number;
+  /** Maximum retry delay in milliseconds (default: 30000) */
+  retryMaxDelayMs: number;
+  /** Number of failures before circuit breaker opens (default: 5) */
+  circuitBreakerThreshold: number;
+  /** Time in milliseconds before circuit breaker attempts reset (default: 30000) */
+  circuitBreakerResetMs: number;
+}
+
+/**
+ * Configuration for a single upstream registry.
+ */
+export interface IUpstreamRegistryConfig {
+  /** Unique identifier for this upstream */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Base URL of the upstream registry (e.g., "https://registry.npmjs.org") */
+  url: string;
+  /** Priority for routing (lower = higher priority, 1 = first) */
+  priority: number;
+  /** Whether this upstream is enabled */
+  enabled: boolean;
+  /** Scope rules for routing (empty = match all) */
+  scopeRules?: IUpstreamScopeRule[];
+  /** Authentication configuration */
+  auth: IUpstreamAuthConfig;
+  /** Cache configuration overrides */
+  cache?: Partial<IUpstreamCacheConfig>;
+  /** Resilience configuration overrides */
+  resilience?: Partial<IUpstreamResilienceConfig>;
+  /** API path prefix for OCI registries (default: /v2). Useful for registries behind reverse proxies. */
+  apiPrefix?: string;
+}
+
+/**
+ * Protocol-level upstream configuration.
+ * Configures upstream behavior for a specific protocol (npm, oci, etc.)
+ */
+export interface IProtocolUpstreamConfig {
+  /** Whether upstream is enabled for this protocol */
+  enabled: boolean;
+  /** List of upstream registries, ordered by priority */
+  upstreams: IUpstreamRegistryConfig[];
+  /** Protocol-level cache configuration defaults */
+  cache?: Partial<IUpstreamCacheConfig>;
+  /** Protocol-level resilience configuration defaults */
+  resilience?: Partial<IUpstreamResilienceConfig>;
+}
+
+/**
+ * Result of an upstream fetch operation.
+ */
+export interface IUpstreamResult {
+  /** Whether the fetch was successful (2xx status) */
+  success: boolean;
+  /** HTTP status code */
+  status: number;
+  /** Response headers */
+  headers: Record<string, string>;
+  /** Response body (Buffer for binary, object for JSON) */
+  body?: Buffer | any;
+  /** ID of the upstream that served the request */
+  upstreamId: string;
+  /** Whether the response was served from cache */
+  fromCache: boolean;
+  /** Request latency in milliseconds */
+  latencyMs: number;
+}
+
+/**
+ * Circuit breaker state.
+ */
+export type TCircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Context for an upstream fetch request.
+ */
+export interface IUpstreamFetchContext {
+  /** Protocol type */
+  protocol: TRegistryProtocol;
+  /** Resource identifier (package name, artifact name, etc.) */
+  resource: string;
+  /** Type of resource being fetched (packument, tarball, manifest, blob, etc.) */
+  resourceType: string;
+  /** Original request path */
+  path: string;
+  /** HTTP method */
+  method: string;
+  /** Request headers */
+  headers: Record<string, string>;
+  /** Query parameters */
+  query: Record<string, string>;
+  /** Actor performing the request (for cache key isolation) */
+  actor?: IRequestActor;
+}
+
+/**
+ * Cache entry stored in the upstream cache.
+ */
+export interface ICacheEntry {
+  /** Cached data */
+  data: Buffer;
+  /** Content type of the cached data */
+  contentType: string;
+  /** Original response headers */
+  headers: Record<string, string>;
+  /** When the entry was cached */
+  cachedAt: Date;
+  /** When the entry expires */
+  expiresAt?: Date;
+  /** ETag for conditional requests */
+  etag?: string;
+  /** ID of the upstream that provided the data */
+  upstreamId: string;
+  /** Whether the entry is stale but still usable */
+  stale?: boolean;
+}
+
+/**
+ * Default cache configuration values.
+ */
+export const DEFAULT_CACHE_CONFIG: IUpstreamCacheConfig = {
+  enabled: true,
+  defaultTtlSeconds: 300,           // 5 minutes
+  immutableTtlSeconds: 2592000,     // 30 days
+  staleWhileRevalidate: true,
+  staleMaxAgeSeconds: 3600,         // 1 hour
+  negativeCacheTtlSeconds: 60,      // 1 minute
+};
+
+/**
+ * Default resilience configuration values.
+ */
+export const DEFAULT_RESILIENCE_CONFIG: IUpstreamResilienceConfig = {
+  timeoutMs: 30000,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+  retryMaxDelayMs: 30000,
+  circuitBreakerThreshold: 5,
+  circuitBreakerResetMs: 30000,
+};
+
+// ============================================================================
+// Upstream Provider Interfaces
+// ============================================================================
+
+/**
+ * Context for resolving upstream configuration.
+ * Passed to IUpstreamProvider per-request to enable dynamic upstream routing.
+ */
+export interface IUpstreamResolutionContext {
+  /** Protocol being accessed */
+  protocol: TRegistryProtocol;
+  /** Resource identifier (package name, repository, coordinates, etc.) */
+  resource: string;
+  /** Extracted scope (e.g., "company" from "@company/pkg", "myorg" from "myorg/image") */
+  scope: string | null;
+  /** Actor performing the request */
+  actor?: IRequestActor;
+  /** HTTP method */
+  method: string;
+  /** Resource type (packument, tarball, manifest, blob, etc.) */
+  resourceType: string;
+}
+
+/**
+ * Dynamic upstream configuration provider.
+ * Implement this interface to provide per-request upstream routing
+ * based on actor context (user, organization, etc.)
+ *
+ * @example
+ * ```typescript
+ * class OrgUpstreamProvider implements IUpstreamProvider {
+ *   constructor(private db: Database) {}
+ *
+ *   async resolveUpstreamConfig(ctx: IUpstreamResolutionContext) {
+ *     if (ctx.actor?.orgId) {
+ *       const orgConfig = await this.db.getOrgUpstream(ctx.actor.orgId, ctx.protocol);
+ *       if (orgConfig) return orgConfig;
+ *     }
+ *     return this.db.getDefaultUpstream(ctx.protocol);
+ *   }
+ * }
+ * ```
+ */
+export interface IUpstreamProvider {
+  /** Optional initialization */
+  init?(): Promise<void>;
+
+  /**
+   * Resolve upstream configuration for a request.
+   * @param context - Information about the current request
+   * @returns Upstream config to use, or null to skip upstream lookup
+   */
+  resolveUpstreamConfig(context: IUpstreamResolutionContext): Promise<IProtocolUpstreamConfig | null>;
+}
+
+/**
+ * Static upstream provider for simple configurations.
+ * Use this when you have fixed upstream registries that don't change per-request.
+ *
+ * @example
+ * ```typescript
+ * const provider = new StaticUpstreamProvider({
+ *   npm: {
+ *     enabled: true,
+ *     upstreams: [{ id: 'npmjs', url: 'https://registry.npmjs.org', priority: 1, enabled: true, auth: { type: 'none' } }],
+ *   },
+ * });
+ * ```
+ */
+export class StaticUpstreamProvider implements IUpstreamProvider {
+  constructor(private configs: Partial<Record<TRegistryProtocol, IProtocolUpstreamConfig>>) {}
+
+  async resolveUpstreamConfig(ctx: IUpstreamResolutionContext): Promise<IProtocolUpstreamConfig | null> {
+    return this.configs[ctx.protocol] ?? null;
+  }
+}

tsconfig.json

@@ -4,9 +4,7 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
-    "verbatimModuleSyntax": true,
-    "baseUrl": ".",
-    "paths": {}
+    "verbatimModuleSyntax": true
   },
   "exclude": ["dist_*/**/*.d.ts"]
 }