@push.rocks/smartregistry 2.5.0 → 2.8.0

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartregistry
 
-> 🚀 A composable TypeScript library implementing **OCI Distribution Specification v1.1**, **NPM Registry API**, **Maven Repository**, **Cargo/crates.io Registry**, **Composer/Packagist**, **PyPI (Python Package Index)**, and **RubyGems Registry** for building unified container and package registries.
+> 🚀 A composable TypeScript library implementing **OCI Distribution Specification v1.1**, **NPM Registry API**, **Maven Repository**, **Cargo/crates.io Registry**, **Composer/Packagist**, **PyPI (Python Package Index)**, and **RubyGems Registry** — everything you need to build a unified container and package registry in one library.
 
 ## Issue Reporting and Security
 
@@ -18,91 +18,57 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - **RubyGems Registry**: Ruby gem registry with compact index protocol
 
 ### 🏗️ Unified Architecture
-- **Composable Design**: Core infrastructure with protocol plugins
-- **Shared Storage**: Cloud-agnostic S3-compatible backend using [@push.rocks/smartbucket](https://www.npmjs.com/package/@push.rocks/smartbucket) with standardized `IS3Descriptor` from [@tsclass/tsclass](https://www.npmjs.com/package/@tsclass/tsclass)
+- **Composable Design**: Core infrastructure with protocol plugins — enable only what you need
+- **Shared Storage**: Cloud-agnostic S3-compatible backend via [@push.rocks/smartbucket](https://www.npmjs.com/package/@push.rocks/smartbucket) with standardized `IS3Descriptor` from [@tsclass/tsclass](https://www.npmjs.com/package/@tsclass/tsclass)
 - **Unified Authentication**: Scope-based permissions across all protocols
-- **Path-based Routing**: `/oci/*` for containers, `/npm/*` for packages, `/maven/*` for Java artifacts, `/cargo/*` for Rust crates, `/composer/*` for PHP packages, `/pypi/*` for Python packages, `/rubygems/*` for Ruby gems
+- **Path-based Routing**: `/oci/*`, `/npm/*`, `/maven/*`, `/cargo/*`, `/composer/*`, `/pypi/*`, `/rubygems/*`
 
 ### 🔐 Authentication & Authorization
 - NPM UUID tokens for package operations
 - OCI JWT tokens for container operations
+- Protocol-specific tokens for Maven, Cargo, Composer, PyPI, and RubyGems
 - Unified scope system: `npm:package:foo:write`, `oci:repository:bar:push`
-- Pluggable via async callbacks
-
-### 📦 Comprehensive Feature Set
-
-**OCI Features:**
-- ✅ Pull operations (manifests, blobs)
-- ✅ Push operations (chunked uploads)
-- ✅ Content discovery (tags, referrers API)
-- ✅ Content management (deletion)
-
-**NPM Features:**
-- ✅ Package publish/unpublish
-- ✅ Package download (tarballs)
-- ✅ Metadata & search
-- ✅ Dist-tag management
-- ✅ Token management
-
-**Maven Features:**
-- ✅ Artifact upload/download
-- ✅ POM and metadata management
-- ✅ Snapshot and release versions
-- ✅ Checksum verification (MD5, SHA1)
-
-**Cargo Features:**
-- ✅ Crate publish (.crate files)
-- ✅ Sparse HTTP protocol (modern index)
-- ✅ Version yank/unyank
-- ✅ Dependency resolution
-- ✅ Search functionality
-
-**Composer Features:**
-- ✅ Package publish/download (ZIP format)
-- ✅ Composer v2 repository API
-- ✅ Package metadata (packages.json)
-- ✅ Version management
-- ✅ Dependency resolution
-- ✅ PSR-4/PSR-0 autoloading support
-
-**PyPI Features:**
-- ✅ PEP 503 Simple Repository API (HTML)
-- ✅ PEP 691 JSON-based Simple API
-- ✅ Package upload (wheel and sdist)
-- ✅ Package name normalization
-- ✅ Hash verification (SHA256, MD5, Blake2b)
-- ✅ Content negotiation (JSON/HTML)
-- ✅ Metadata API (JSON endpoints)
-
-**RubyGems Features:**
-- ✅ Compact Index protocol (modern Bundler)
-- ✅ Gem publish/download (.gem files)
-- ✅ Version yank/unyank
-- ✅ Platform-specific gems
-- ✅ Dependency resolution
-- ✅ Legacy API compatibility
+- **Pluggable Auth Provider** (`IAuthProvider`): Integrate LDAP, OAuth, SSO, or any custom auth
+
+### 📦 Protocol Feature Matrix
+
+| Feature | OCI | NPM | Maven | Cargo | Composer | PyPI | RubyGems |
+|---------|-----|-----|-------|-------|----------|------|----------|
+| Publish/Upload | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Download | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Search | — | ✅ | — | ✅ | — | — | — |
+| Version Yank | — | — | — | ✅ | — | — | ✅ |
+| Metadata API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Token Auth | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Checksum Verification | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Upstream Proxy | ✅ | ✅ | — | — | — | — | — |
 
 ### 🌐 Upstream Proxy & Caching
 - **Multi-Upstream Support**: Configure multiple upstream registries per protocol with priority ordering
 - **Scope-Based Routing**: Route specific packages/scopes to different upstreams (e.g., `@company/*` → private registry)
-- **S3-Backed Cache**: Persistent caching using existing S3 storage with URL-based cache paths
+- **S3-Backed Cache**: Persistent caching using existing S3 storage
 - **Circuit Breaker**: Automatic failover with configurable thresholds
 - **Stale-While-Revalidate**: Serve cached content while refreshing in background
 - **Content-Aware TTLs**: Different TTLs for immutable (tarballs) vs mutable (metadata) content
 
+### 🌊 Streaming-First Architecture
+- **Web Streams API** (`ReadableStream<Uint8Array>`) — cross-runtime (Node, Deno, Bun)
+- **Zero-copy downloads**: Binary artifacts stream directly from S3 to the HTTP response
+- **OCI upload streaming**: Chunked blob uploads stored as temp S3 objects, not accumulated in memory
+- **Unified response type**: Every `response.body` is a `ReadableStream` — one pattern for all consumers
+
 ### 🔌 Enterprise Extensibility
-- **Pluggable Auth Provider** (`IAuthProvider`): Integrate LDAP, OAuth, SSO, or custom auth systems
 - **Storage Event Hooks** (`IStorageHooks`): Quota tracking, audit logging, virus scanning, cache invalidation
 - **Request Actor Context**: Pass user/org info through requests for audit trails and rate limiting
 
 ## 📥 Installation
 
 ```bash
-# Using npm
-npm install @push.rocks/smartregistry
-
 # Using pnpm (recommended)
 pnpm add @push.rocks/smartregistry
+
+# Using npm
+npm install @push.rocks/smartregistry
 ```
 
 ## 🚀 Quick Start
@@ -130,40 +96,20 @@ const config: IRegistryConfig = {
       service: 'my-registry',
     },
   },
-  oci: {
-    enabled: true,
-    basePath: '/oci',
-  },
-  npm: {
-    enabled: true,
-    basePath: '/npm',
-  },
-  maven: {
-    enabled: true,
-    basePath: '/maven',
-  },
-  cargo: {
-    enabled: true,
-    basePath: '/cargo',
-  },
-  composer: {
-    enabled: true,
-    basePath: '/composer',
-  },
-  pypi: {
-    enabled: true,
-    basePath: '/pypi',
-  },
-  rubygems: {
-    enabled: true,
-    basePath: '/rubygems',
-  },
+  // Enable only the protocols you need
+  oci: { enabled: true, basePath: '/oci' },
+  npm: { enabled: true, basePath: '/npm' },
+  maven: { enabled: true, basePath: '/maven' },
+  cargo: { enabled: true, basePath: '/cargo' },
+  composer: { enabled: true, basePath: '/composer' },
+  pypi: { enabled: true, basePath: '/pypi' },
+  rubygems: { enabled: true, basePath: '/rubygems' },
 };
 
 const registry = new SmartRegistry(config);
 await registry.init();
 
-// Handle requests
+// Handle any incoming HTTP request — the router does the rest
 const response = await registry.handleRequest({
   method: 'GET',
   path: '/npm/express',
@@ -174,6 +120,27 @@ const response = await registry.handleRequest({
 
 ## 🏛️ Architecture
 
+### Request Flow
+
+```
+HTTP Request
+    ↓
+SmartRegistry (orchestrator)
+    ↓
+Path-based routing
+    ├─→ /oci/*       → OciRegistry
+    ├─→ /npm/*       → NpmRegistry
+    ├─→ /maven/*     → MavenRegistry
+    ├─→ /cargo/*     → CargoRegistry
+    ├─→ /composer/*  → ComposerRegistry
+    ├─→ /pypi/*      → PypiRegistry
+    └─→ /rubygems/*  → RubyGemsRegistry
+           ↓
+    Shared Storage & Auth
+           ↓
+    S3-compatible backend
+```
+
 ### Directory Structure
 
 ```
@@ -184,59 +151,33 @@ ts/
 │   ├── classes.authmanager.ts
 │   └── interfaces.core.ts
 ├── oci/                     # OCI implementation
-│   ├── classes.ociregistry.ts
-│   └── interfaces.oci.ts
 ├── npm/                     # NPM implementation
-│   ├── classes.npmregistry.ts
-│   └── interfaces.npm.ts
 ├── maven/                   # Maven implementation
 ├── cargo/                   # Cargo implementation
 ├── composer/                # Composer implementation
 ├── pypi/                    # PyPI implementation
 ├── rubygems/                # RubyGems implementation
+├── upstream/                # Upstream proxy infrastructure
 └── classes.smartregistry.ts # Main orchestrator
 ```
 
-### Request Flow
-
-```
-HTTP Request
-    ↓
-SmartRegistry (orchestrator)
-    ↓
-Path-based routing
-    ├─→ /oci/* → OciRegistry
-    ├─→ /npm/* → NpmRegistry
-    ├─→ /maven/* → MavenRegistry
-    ├─→ /cargo/* → CargoRegistry
-    ├─→ /composer/* → ComposerRegistry
-    ├─→ /pypi/* → PypiRegistry
-    └─→ /rubygems/* → RubyGemsRegistry
-           ↓
-    Shared Storage & Auth
-           ↓
-    S3-compatible backend
-```
-
 ## 💡 Usage Examples
 
 ### 🐳 OCI Registry (Container Images)
 
 ```typescript
-// Pull an image
+// Pull a manifest
 const response = await registry.handleRequest({
   method: 'GET',
-  path: '/oci/v2/library/nginx/manifests/latest',
-  headers: {
-    'Authorization': 'Bearer <token>',
-  },
+  path: '/oci/library/nginx/manifests/latest',
+  headers: { 'Authorization': 'Bearer <token>' },
   query: {},
 });
 
-// Push a blob
+// Push a blob (two-step upload)
 const uploadInit = await registry.handleRequest({
   method: 'POST',
-  path: '/oci/v2/myapp/blobs/uploads/',
+  path: '/oci/myapp/blobs/uploads/',
   headers: { 'Authorization': 'Bearer <token>' },
   query: {},
 });
@@ -245,17 +186,17 @@ const uploadId = uploadInit.headers['Docker-Upload-UUID'];
 
 await registry.handleRequest({
   method: 'PUT',
-  path: `/oci/v2/myapp/blobs/uploads/${uploadId}`,
+  path: `/oci/myapp/blobs/uploads/${uploadId}`,
   headers: { 'Authorization': 'Bearer <token>' },
   query: { digest: 'sha256:abc123...' },
   body: blobData,
 });
 ```
 
-### 📦 NPM Registry (Packages)
+### 📦 NPM Registry
 
 ```typescript
-// Install a package (get metadata)
+// Get package metadata
 const metadata = await registry.handleRequest({
   method: 'GET',
   path: '/npm/express',
@@ -263,14 +204,6 @@ const metadata = await registry.handleRequest({
   query: {},
 });
 
-// Download tarball
-const tarball = await registry.handleRequest({
-  method: 'GET',
-  path: '/npm/express/-/express-4.18.0.tgz',
-  headers: {},
-  query: {},
-});
-
 // Publish a package
 const publishResponse = await registry.handleRequest({
   method: 'PUT',
@@ -279,9 +212,7 @@ const publishResponse = await registry.handleRequest({
   query: {},
   body: {
     name: 'my-package',
-    versions: {
-      '1.0.0': { /* version metadata */ },
-    },
+    versions: { '1.0.0': { /* version metadata */ } },
     'dist-tags': { latest: '1.0.0' },
     _attachments: {
       'my-package-1.0.0.tgz': {
@@ -294,7 +225,7 @@ const publishResponse = await registry.handleRequest({
 });
 
 // Search packages
-const searchResults = await registry.handleRequest({
+const search = await registry.handleRequest({
   method: 'GET',
   path: '/npm/-/v1/search',
   headers: {},
@@ -305,7 +236,7 @@ const searchResults = await registry.handleRequest({
 ### 🦀 Cargo Registry (Rust Crates)
 
 ```typescript
-// Get config.json (required for Cargo)
+// Get registry config (required for Cargo sparse protocol)
 const config = await registry.handleRequest({
   method: 'GET',
   path: '/cargo/config.json',
@@ -313,54 +244,22 @@ const config = await registry.handleRequest({
   query: {},
 });
 
-// Get index file for a crate
-const index = await registry.handleRequest({
-  method: 'GET',
-  path: '/cargo/se/rd/serde',  // Path based on crate name length
-  headers: {},
-  query: {},
-});
-
-// Download a crate file
-const crateFile = await registry.handleRequest({
-  method: 'GET',
-  path: '/cargo/api/v1/crates/serde/1.0.0/download',
-  headers: {},
-  query: {},
-});
-
 // Publish a crate (binary format: [4 bytes JSON len][JSON][4 bytes crate len][.crate])
 const publishResponse = await registry.handleRequest({
   method: 'PUT',
   path: '/cargo/api/v1/crates/new',
-  headers: { 'Authorization': '<cargo-token>' },  // No "Bearer" prefix
+  headers: { 'Authorization': '<cargo-token>' },
   query: {},
-  body: binaryPublishData,  // Length-prefixed binary format
+  body: binaryPublishData,
 });
 
-// Yank a version (deprecate without deleting)
-const yankResponse = await registry.handleRequest({
+// Yank a version
+await registry.handleRequest({
   method: 'DELETE',
   path: '/cargo/api/v1/crates/my-crate/0.1.0/yank',
   headers: { 'Authorization': '<cargo-token>' },
   query: {},
 });
-
-// Unyank a version
-const unyankResponse = await registry.handleRequest({
-  method: 'PUT',
-  path: '/cargo/api/v1/crates/my-crate/0.1.0/unyank',
-  headers: { 'Authorization': '<cargo-token>' },
-  query: {},
-});
-
-// Search crates
-const search = await registry.handleRequest({
-  method: 'GET',
-  path: '/cargo/api/v1/crates',
-  headers: {},
-  query: { q: 'serde', per_page: '10' },
-});
 ```
 
 **Using with Cargo CLI:**
@@ -369,28 +268,17 @@ const search = await registry.handleRequest({
 # .cargo/config.toml
 [registries.myregistry]
 index = "sparse+https://registry.example.com/cargo/"
-
-[registries.myregistry.credential-provider]
-# Or use credentials directly:
-# [registries.myregistry]
-# token = "your-api-token"
 ```
 
 ```bash
-# Publish to custom registry
 cargo publish --registry=myregistry
-
-# Install from custom registry
 cargo install --registry=myregistry my-crate
-
-# Search custom registry
-cargo search --registry=myregistry tokio
 ```
 
 ### 🎼 Composer Registry (PHP Packages)
 
 ```typescript
-// Get repository root (packages.json)
+// Get repository root
 const packagesJson = await registry.handleRequest({
   method: 'GET',
   path: '/composer/packages.json',
@@ -398,75 +286,34 @@ const packagesJson = await registry.handleRequest({
   query: {},
 });
 
-// Get package metadata
-const metadata = await registry.handleRequest({
-  method: 'GET',
-  path: '/composer/p2/vendor/package.json',
-  headers: {},
-  query: {},
-});
-
-// Upload a package (ZIP with composer.json)
-const zipBuffer = await readFile('package.zip');
+// Upload a package (ZIP with composer.json inside)
 const uploadResponse = await registry.handleRequest({
   method: 'PUT',
   path: '/composer/packages/vendor/package',
-  headers: { 'Authorization': `Bearer <composer-token>` },
+  headers: { 'Authorization': 'Bearer <composer-token>' },
   query: {},
   body: zipBuffer,
 });
-
-// Download package ZIP
-const download = await registry.handleRequest({
-  method: 'GET',
-  path: '/composer/dists/vendor/package/ref123.zip',
-  headers: {},
-  query: {},
-});
-
-// List all packages
-const list = await registry.handleRequest({
-  method: 'GET',
-  path: '/composer/packages/list.json',
-  headers: {},
-  query: {},
-});
-
-// Delete a specific version
-const deleteVersion = await registry.handleRequest({
-  method: 'DELETE',
-  path: '/composer/packages/vendor/package/1.0.0',
-  headers: { 'Authorization': `Bearer <composer-token>` },
-  query: {},
-});
 ```
 
 **Using with Composer CLI:**
 
 ```json
-// composer.json
 {
   "repositories": [
-    {
-      "type": "composer",
-      "url": "https://registry.example.com/composer"
-    }
+    { "type": "composer", "url": "https://registry.example.com/composer" }
   ]
 }
 ```
 
 ```bash
-# Install from custom registry
 composer require vendor/package
-
-# Update packages
-composer update
 ```
 
 ### 🐍 PyPI Registry (Python Packages)
 
 ```typescript
-// Get package index (PEP 503 HTML format)
+// Get package index (PEP 503 HTML)
 const htmlIndex = await registry.handleRequest({
   method: 'GET',
   path: '/simple/requests/',
@@ -474,7 +321,7 @@ const htmlIndex = await registry.handleRequest({
   query: {},
 });
 
-// Get package index (PEP 691 JSON format)
+// Get package index (PEP 691 JSON)
 const jsonIndex = await registry.handleRequest({
   method: 'GET',
   path: '/simple/requests/',
@@ -482,89 +329,38 @@ const jsonIndex = await registry.handleRequest({
   query: {},
 });
 
-// Upload a Python package (wheel or sdist)
-const formData = new FormData();
-formData.append(':action', 'file_upload');
-formData.append('protocol_version', '1');
-formData.append('name', 'my-package');
-formData.append('version', '1.0.0');
-formData.append('filetype', 'bdist_wheel');
-formData.append('pyversion', 'py3');
-formData.append('metadata_version', '2.1');
-formData.append('sha256_digest', 'abc123...');
-formData.append('content', packageFile, { filename: 'my_package-1.0.0-py3-none-any.whl' });
-
+// Upload a package
 const upload = await registry.handleRequest({
   method: 'POST',
-  path: '/pypi/legacy/',
+  path: '/pypi/',
   headers: {
-    'Authorization': `Bearer <pypi-token>`,
+    'Authorization': 'Bearer <pypi-token>',
     'Content-Type': 'multipart/form-data',
   },
   query: {},
-  body: formData,
-});
-
-// Get package metadata (PyPI JSON API)
-const metadata = await registry.handleRequest({
-  method: 'GET',
-  path: '/pypi/my-package/json',
-  headers: {},
-  query: {},
-});
-
-// Download a specific version
-const download = await registry.handleRequest({
-  method: 'GET',
-  path: '/packages/my-package/my_package-1.0.0-py3-none-any.whl',
-  headers: {},
-  query: {},
+  body: {
+    ':action': 'file_upload',
+    protocol_version: '1',
+    name: 'my-package',
+    version: '1.0.0',
+    filetype: 'bdist_wheel',
+    content: wheelData,
+    filename: 'my_package-1.0.0-py3-none-any.whl',
+  },
 });
 ```
 
 **Using with pip:**
 
 ```bash
-# Install from custom registry
 pip install --index-url https://registry.example.com/simple/ my-package
-
-# Upload to custom registry
-python -m twine upload --repository-url https://registry.example.com/pypi/legacy/ dist/*
-
-# Configure in pip.conf or pip.ini
-[global]
-index-url = https://registry.example.com/simple/
+python -m twine upload --repository-url https://registry.example.com/pypi/ dist/*
 ```
 
-### 💎 RubyGems Registry (Ruby Gems)
+### 💎 RubyGems Registry
 
 ```typescript
-// Get versions file (compact index)
-const versions = await registry.handleRequest({
-  method: 'GET',
-  path: '/rubygems/versions',
-  headers: {},
-  query: {},
-});
-
-// Get gem-specific info
-const gemInfo = await registry.handleRequest({
-  method: 'GET',
-  path: '/rubygems/info/rails',
-  headers: {},
-  query: {},
-});
-
-// Get list of all gem names
-const names = await registry.handleRequest({
-  method: 'GET',
-  path: '/rubygems/names',
-  headers: {},
-  query: {},
-});
-
-// Upload a gem file
-const gemBuffer = await readFile('my-gem-1.0.0.gem');
+// Upload a gem
 const uploadGem = await registry.handleRequest({
   method: 'POST',
   path: '/rubygems/api/v1/gems',
@@ -573,34 +369,10 @@ const uploadGem = await registry.handleRequest({
   body: gemBuffer,
 });
 
-// Yank a version (make unavailable for install)
-const yank = await registry.handleRequest({
-  method: 'DELETE',
-  path: '/rubygems/api/v1/gems/yank',
-  headers: { 'Authorization': '<rubygems-api-key>' },
-  query: { gem_name: 'my-gem', version: '1.0.0' },
-});
-
-// Unyank a version
-const unyank = await registry.handleRequest({
-  method: 'PUT',
-  path: '/rubygems/api/v1/gems/unyank',
-  headers: { 'Authorization': '<rubygems-api-key>' },
-  query: { gem_name: 'my-gem', version: '1.0.0' },
-});
-
-// Get gem version metadata
-const versionMeta = await registry.handleRequest({
-  method: 'GET',
-  path: '/rubygems/api/v1/versions/rails.json',
-  headers: {},
-  query: {},
-});
-
-// Download gem file
-const gemDownload = await registry.handleRequest({
+// Get compact index
+const versions = await registry.handleRequest({
   method: 'GET',
-  path: '/rubygems/gems/rails-7.0.0.gem',
+  path: '/rubygems/versions',
   headers: {},
   query: {},
 });
@@ -612,180 +384,114 @@ const gemDownload = await registry.handleRequest({
 # Gemfile
 source 'https://registry.example.com/rubygems' do
   gem 'my-gem'
-  gem 'rails'
 end
 ```
 
 ```bash
-# Install gems
-bundle install
-
-# Push gem to custom registry
 gem push my-gem-1.0.0.gem --host https://registry.example.com/rubygems
-
-# Configure gem source
-gem sources --add https://registry.example.com/rubygems/
-gem sources --remove https://rubygems.org/
+bundle install
 ```
 
 ### 🔐 Authentication
 
 ```typescript
-// Get auth manager instance
 const authManager = registry.getAuthManager();
 
 // Authenticate user
-const userId = await authManager.authenticate({
-  username: 'user',
-  password: 'pass',
-});
+const userId = await authManager.authenticate({ username: 'user', password: 'pass' });
 
-// Create NPM token
+// Create protocol-specific tokens
 const npmToken = await authManager.createNpmToken(userId, false);
+const ociToken = await authManager.createOciToken(userId, ['oci:repository:myapp:push'], 3600);
+const pypiToken = await authManager.createPypiToken(userId, false);
+const cargoToken = await authManager.createCargoToken(userId, false);
+const composerToken = await authManager.createComposerToken(userId, false);
+const rubygemsToken = await authManager.createRubyGemsToken(userId, false);
 
-// Create OCI token with scopes
-const ociToken = await authManager.createOciToken(
-  userId,
-  ['oci:repository:myapp:push', 'oci:repository:myapp:pull'],
-  3600
-);
-
-// Validate any token
+// Validate and check permissions
 const token = await authManager.validateToken(npmToken, 'npm');
-
-// Check permissions
-const canWrite = await authManager.authorize(
-  token,
-  'npm:package:my-package',
-  'write'
-);
+const canWrite = await authManager.authorize(token, 'npm:package:my-package', 'write');
 ```
 
 ### 🌐 Upstream Proxy Configuration
 
 ```typescript
-import { SmartRegistry, IRegistryConfig } from '@push.rocks/smartregistry';
+import { SmartRegistry, StaticUpstreamProvider } from '@push.rocks/smartregistry';
 
-const config: IRegistryConfig = {
-  storage: { /* S3 config */ },
-  auth: { /* Auth config */ },
+const upstreamProvider = new StaticUpstreamProvider({
   npm: {
     enabled: true,
-    basePath: '/npm',
-    upstream: {
-      enabled: true,
-      upstreams: [
-        {
-          id: 'company-private',
-          name: 'Company Private NPM',
-          url: 'https://npm.internal.company.com',
-          priority: 1,  // Lower = higher priority
-          enabled: true,
-          scopeRules: [
-            { pattern: '@company/*', action: 'include' },
-            { pattern: '@internal/*', action: 'include' },
-          ],
-          auth: { type: 'bearer', token: process.env.NPM_PRIVATE_TOKEN },
-        },
-        {
-          id: 'npmjs',
-          name: 'NPM Public Registry',
-          url: 'https://registry.npmjs.org',
-          priority: 10,
-          enabled: true,
-          scopeRules: [
-            { pattern: '@company/*', action: 'exclude' },
-            { pattern: '@internal/*', action: 'exclude' },
-          ],
-          auth: { type: 'none' },
-          cache: { defaultTtlSeconds: 300 },
-          resilience: { timeoutMs: 30000, maxRetries: 3 },
-        },
-      ],
-      cache: { enabled: true, staleWhileRevalidate: true },
-    },
+    upstreams: [
+      {
+        id: 'company-private',
+        url: 'https://npm.internal.company.com',
+        priority: 1,
+        enabled: true,
+        scopeRules: [{ pattern: '@company/*', action: 'include' }],
+        auth: { type: 'bearer', token: process.env.NPM_PRIVATE_TOKEN },
+      },
+      {
+        id: 'npmjs',
+        url: 'https://registry.npmjs.org',
+        priority: 10,
+        enabled: true,
+        scopeRules: [{ pattern: '@company/*', action: 'exclude' }],
+      },
+    ],
+    cache: { enabled: true, staleWhileRevalidate: true },
   },
   oci: {
     enabled: true,
-    basePath: '/oci',
-    upstream: {
-      enabled: true,
-      upstreams: [
-        {
-          id: 'dockerhub',
-          name: 'Docker Hub',
-          url: 'https://registry-1.docker.io',
-          priority: 1,
-          enabled: true,
-          auth: { type: 'none' },
-        },
-        {
-          id: 'ghcr',
-          name: 'GitHub Container Registry',
-          url: 'https://ghcr.io',
-          priority: 2,
-          enabled: true,
-          scopeRules: [{ pattern: 'ghcr.io/*', action: 'include' }],
-          auth: { type: 'bearer', token: process.env.GHCR_TOKEN },
-        },
-      ],
-    },
+    upstreams: [
+      { id: 'dockerhub', url: 'https://registry-1.docker.io', priority: 1, enabled: true },
+    ],
   },
-};
-
-const registry = new SmartRegistry(config);
-await registry.init();
+});
 
-// Requests for @company/* packages go to private registry
-// Other packages proxy through to npmjs.org with caching
+const registry = new SmartRegistry({
+  storage: { /* S3 config */ },
+  auth: { /* Auth config */ },
+  upstreamProvider,
+  npm: { enabled: true, basePath: '/npm' },
+  oci: { enabled: true, basePath: '/oci' },
+});
 ```
 
 ### 🔌 Custom Auth Provider
 
 ```typescript
-import { SmartRegistry, IAuthProvider, IAuthToken, ICredentials, TRegistryProtocol } from '@push.rocks/smartregistry';
+import { SmartRegistry, IAuthProvider, IAuthToken, TRegistryProtocol } from '@push.rocks/smartregistry';
 
-// Implement custom auth (e.g., LDAP, OAuth)
 class LdapAuthProvider implements IAuthProvider {
-  constructor(private ldapClient: LdapClient) {}
+  async init() { /* connect to LDAP */ }
 
-  async authenticate(credentials: ICredentials): Promise<string | null> {
+  async authenticate(credentials) {
     const result = await this.ldapClient.bind(credentials.username, credentials.password);
     return result.success ? credentials.username : null;
   }
 
   async validateToken(token: string, protocol?: TRegistryProtocol): Promise<IAuthToken | null> {
     const session = await this.sessionStore.get(token);
-    if (!session) return null;
-    return {
-      userId: session.userId,
-      scopes: session.scopes,
-      readonly: session.readonly,
-      created: session.created,
-    };
+    return session ? { userId: session.userId, scopes: session.scopes } : null;
   }
 
-  async createToken(userId: string, protocol: TRegistryProtocol, options?: ITokenOptions): Promise<string> {
+  async createToken(userId: string, protocol: TRegistryProtocol, options?) {
     const token = crypto.randomUUID();
     await this.sessionStore.set(token, { userId, protocol, ...options });
     return token;
   }
 
-  async revokeToken(token: string): Promise<void> {
-    await this.sessionStore.delete(token);
-  }
+  async revokeToken(token: string) { await this.sessionStore.delete(token); }
 
-  async authorize(token: IAuthToken | null, resource: string, action: string): Promise<boolean> {
-    if (!token) return action === 'read'; // Anonymous read-only
-    // Check LDAP groups, roles, etc.
+  async authorize(token: IAuthToken | null, resource: string, action: string) {
+    if (!token) return action === 'read';
     return this.checkPermissions(token.userId, resource, action);
   }
 }
 
-// Use custom provider
 const registry = new SmartRegistry({
   ...config,
-  authProvider: new LdapAuthProvider(ldapClient),
+  authProvider: new LdapAuthProvider(),
 });
 ```
 
@@ -795,12 +501,10 @@ const registry = new SmartRegistry({
 import { SmartRegistry, IStorageHooks, IStorageHookContext } from '@push.rocks/smartregistry';
 
 const storageHooks: IStorageHooks = {
-  // Block uploads that exceed quota
   async beforePut(ctx: IStorageHookContext) {
     if (ctx.actor?.orgId) {
       const usage = await getStorageUsage(ctx.actor.orgId);
       const quota = await getQuota(ctx.actor.orgId);
-
       if (usage + (ctx.metadata?.size || 0) > quota) {
         return { allowed: false, reason: 'Storage quota exceeded' };
       }
@@ -808,13 +512,7 @@ const storageHooks: IStorageHooks = {
     return { allowed: true };
   },
 
-  // Update usage tracking after successful upload
   async afterPut(ctx: IStorageHookContext) {
-    if (ctx.actor?.orgId && ctx.metadata?.size) {
-      await incrementUsage(ctx.actor.orgId, ctx.metadata.size);
-    }
-
-    // Audit log
     await auditLog.write({
       action: 'storage.put',
       key: ctx.key,
@@ -824,35 +522,21 @@ const storageHooks: IStorageHooks = {
     });
   },
 
-  // Prevent deletion of protected packages
   async beforeDelete(ctx: IStorageHookContext) {
     if (await isProtectedPackage(ctx.key)) {
       return { allowed: false, reason: 'Cannot delete protected package' };
     }
     return { allowed: true };
   },
-
-  // Log all access for compliance
-  async afterGet(ctx: IStorageHookContext) {
-    await accessLog.write({
-      action: 'storage.get',
-      key: ctx.key,
-      actor: ctx.actor,
-      timestamp: ctx.timestamp,
-    });
-  },
 };
 
-const registry = new SmartRegistry({
-  ...config,
-  storageHooks,
-});
+const registry = new SmartRegistry({ ...config, storageHooks });
 ```
 
 ### 👤 Request Actor Context
 
 ```typescript
-// Pass actor information through requests for audit/quota tracking
+// Pass actor information for audit/quota tracking
 const response = await registry.handleRequest({
   method: 'PUT',
   path: '/npm/my-package',
@@ -865,35 +549,25 @@ const response = await registry.handleRequest({
     ip: req.ip,
     userAgent: req.headers['user-agent'],
     orgId: 'org-456',
-    sessionId: 'session-xyz',
   },
 });
-
-// Actor info is available in storage hooks for quota/audit
 ```
 
 ## ⚙️ Configuration
 
 ### Storage Configuration
 
-The storage configuration extends `IS3Descriptor` from `@tsclass/tsclass` for standardized S3 configuration:
+Extends `IS3Descriptor` from `@tsclass/tsclass`:
 
 ```typescript
-import type { IS3Descriptor } from '@tsclass/tsclass';
-
-storage: IS3Descriptor & {
-  bucketName: string;       // Bucket name for registry storage
-}
-
-// Example:
 storage: {
   accessKey: string;        // S3 access key
   accessSecret: string;     // S3 secret key
   endpoint: string;         // S3 endpoint (e.g., 's3.amazonaws.com')
   port?: number;            // Default: 443
   useSsl?: boolean;         // Default: true
-  region?: string;          // AWS region (e.g., 'us-east-1')
-  bucketName: string;       // Bucket name for this registry
+  region?: string;          // AWS region
+  bucketName: string;       // Bucket name for registry storage
 }
 ```
 
@@ -901,306 +575,227 @@ storage: {
 
 ```typescript
 auth: {
-  jwtSecret: string;        // Secret for signing JWTs
+  jwtSecret: string;
   tokenStore: 'memory' | 'redis' | 'database';
-  npmTokens: {
-    enabled: boolean;
-    defaultReadonly?: boolean;
-  };
-  ociTokens: {
-    enabled: boolean;
-    realm: string;          // Auth server URL
-    service: string;        // Service name
-  };
+  npmTokens: { enabled: boolean; defaultReadonly?: boolean };
+  ociTokens: { enabled: boolean; realm: string; service: string };
+  pypiTokens: { enabled: boolean };
+  rubygemsTokens: { enabled: boolean };
 }
 ```
 
 ### Protocol Configuration
 
-```typescript
-oci?: {
-  enabled: boolean;
-  basePath: string;         // Default: '/oci'
-  features?: {
-    referrers?: boolean;
-    deletion?: boolean;
-  };
-}
+Each protocol accepts:
 
-npm?: {
+```typescript
+{
   enabled: boolean;
-  basePath: string;         // Default: '/npm'
-  features?: {
-    publish?: boolean;
-    unpublish?: boolean;
-    search?: boolean;
-  };
+  basePath: string;         // URL prefix, e.g. '/npm'
+  registryUrl?: string;     // Public-facing base URL (used in generated metadata links)
+  features?: Record<string, boolean>;
 }
 ```
 
+The `registryUrl` is important when the registry is served behind a reverse proxy or on a non-default port. For example, if your server is at `https://registry.example.com`, set `registryUrl: 'https://registry.example.com/npm'` for the NPM protocol so that generated metadata URLs point to the correct host.
+
 ## 📚 API Reference
 
 ### Core Classes
 
 #### SmartRegistry
 
-Main orchestrator class that routes requests to appropriate protocol handlers.
-
-**Methods:**
-- `init()` - Initialize the registry
-- `handleRequest(context)` - Handle HTTP request
-- `getStorage()` - Get storage instance
-- `getAuthManager()` - Get auth manager
-- `getRegistry(protocol)` - Get protocol handler
-
-#### RegistryStorage
-
-Unified storage abstraction for both OCI and NPM content.
-
-**OCI Methods:**
-- `getOciBlob(digest)` - Get blob
-- `putOciBlob(digest, data)` - Store blob
-- `getOciManifest(repo, digest)` - Get manifest
-- `putOciManifest(repo, digest, data, type)` - Store manifest
-
-**NPM Methods:**
-- `getNpmPackument(name)` - Get package metadata
-- `putNpmPackument(name, data)` - Store package metadata
-- `getNpmTarball(name, version)` - Get tarball
-- `putNpmTarball(name, version, data)` - Store tarball
-
-**PyPI Methods:**
-- `getPypiPackageMetadata(name)` - Get package metadata
-- `putPypiPackageMetadata(name, data)` - Store package metadata
-- `getPypiPackageFile(name, filename)` - Get package file
-- `putPypiPackageFile(name, filename, data)` - Store package file
-
-**RubyGems Methods:**
-- `getRubyGemsVersions()` - Get versions index
-- `putRubyGemsVersions(data)` - Store versions index
-- `getRubyGemsInfo(gemName)` - Get gem info
-- `putRubyGemsInfo(gemName, data)` - Store gem info
-- `getRubyGem(gemName, version)` - Get .gem file
-- `putRubyGem(gemName, version, data)` - Store .gem file
-
-#### AuthManager
-
-Unified authentication manager supporting both NPM and OCI authentication schemes.
-
-**Methods:**
-- `authenticate(credentials)` - Validate user credentials
-- `createNpmToken(userId, readonly)` - Create NPM token
-- `createOciToken(userId, scopes, expiresIn)` - Create OCI JWT
-- `validateToken(token, protocol)` - Validate any token
-- `authorize(token, resource, action)` - Check permissions
-
-### Protocol Handlers
-
-#### OciRegistry
-
-OCI Distribution Specification v1.1 compliant registry.
-
-**Endpoints:**
-- `GET /v2/` - Version check
-- `GET /v2/{name}/manifests/{ref}` - Get manifest
-- `PUT /v2/{name}/manifests/{ref}` - Push manifest
-- `GET /v2/{name}/blobs/{digest}` - Get blob
-- `POST /v2/{name}/blobs/uploads/` - Initiate upload
-- `PUT /v2/{name}/blobs/uploads/{uuid}` - Complete upload
-- `GET /v2/{name}/tags/list` - List tags
-- `GET /v2/{name}/referrers/{digest}` - Get referrers
-
-#### NpmRegistry
-
-NPM registry API compliant implementation.
-
-**Endpoints:**
-- `GET /{package}` - Get package metadata
-- `PUT /{package}` - Publish package
-- `GET /{package}/-/{tarball}` - Download tarball
-- `GET /-/v1/search` - Search packages
-- `PUT /-/user/org.couchdb.user:{user}` - Login
-- `GET /-/npm/v1/tokens` - List tokens
-- `POST /-/npm/v1/tokens` - Create token
-- `PUT /-/package/{pkg}/dist-tags/{tag}` - Update tag
-
-#### CargoRegistry
-
-Cargo/crates.io registry with sparse HTTP protocol support.
-
-**Endpoints:**
-- `GET /config.json` - Registry configuration (sparse protocol)
-- `GET /index/{path}` - Index files (hierarchical structure)
-  - `/1/{name}` - 1-character crate names
-  - `/2/{name}` - 2-character crate names
-  - `/3/{c}/{name}` - 3-character crate names
-  - `/{p1}/{p2}/{name}` - 4+ character crate names
-- `PUT /api/v1/crates/new` - Publish crate (binary format)
-- `GET /api/v1/crates/{crate}/{version}/download` - Download .crate file
-- `DELETE /api/v1/crates/{crate}/{version}/yank` - Yank (deprecate) version
-- `PUT /api/v1/crates/{crate}/{version}/unyank` - Unyank version
-- `GET /api/v1/crates?q={query}` - Search crates
-
-**Index Format:**
-- Newline-delimited JSON (one line per version)
-- SHA256 checksums for .crate files
-- Yanked flag (keep files, mark unavailable)
-
-#### ComposerRegistry
-
-Composer v2 repository API compliant implementation.
-
-**Endpoints:**
-- `GET /packages.json` - Repository metadata and configuration
-- `GET /p2/{vendor}/{package}.json` - Package version metadata
-- `GET /p2/{vendor}/{package}~dev.json` - Dev versions metadata
-- `GET /packages/list.json` - List all packages
-- `GET /dists/{vendor}/{package}/{ref}.zip` - Download package ZIP
-- `PUT /packages/{vendor}/{package}` - Upload package (requires auth)
-- `DELETE /packages/{vendor}/{package}` - Delete entire package
-- `DELETE /packages/{vendor}/{package}/{version}` - Delete specific version
-
-#### PypiRegistry
-
-PyPI (Python Package Index) registry implementing PEP 503 and PEP 691.
-
-**Endpoints:**
-- `GET /simple/` - List all packages (HTML or JSON)
-- `GET /simple/{package}/` - List package files (HTML or JSON)
-- `POST /legacy/` - Upload package (multipart/form-data)
-- `GET /pypi/{package}/json` - Package metadata API
-- `GET /pypi/{package}/{version}/json` - Version-specific metadata
-- `GET /packages/{package}/{filename}` - Download package file
-
-**Features:**
-- PEP 503 Simple Repository API (HTML)
-- PEP 691 JSON-based Simple API
-- Content negotiation via Accept header
-- Package name normalization
-- Hash verification (SHA256, MD5, Blake2b)
-
-#### RubyGemsRegistry
-
-RubyGems registry with compact index protocol for modern Bundler.
-
-**Endpoints:**
-- `GET /versions` - Master versions file (all gems)
-- `GET /info/{gem}` - Gem-specific info file
-- `GET /names` - List of all gem names
-- `POST /api/v1/gems` - Upload gem file
-- `DELETE /api/v1/gems/yank` - Yank (deprecate) version
-- `PUT /api/v1/gems/unyank` - Unyank version
-- `GET /api/v1/versions/{gem}.json` - Version metadata
-- `GET /gems/{gem}-{version}.gem` - Download gem file
-
-**Features:**
-- Compact Index format (append-only text files)
-- Platform-specific gems support
-- Yank/unyank functionality
-- Checksum calculations (MD5 for index, SHA256 for gems)
-- Legacy Marshal API compatibility
+Main orchestrator — routes requests to the appropriate protocol handler.
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize the registry and all enabled protocols |
+| `handleRequest(context)` | Route and handle an HTTP request |
+| `getStorage()` | Get the shared `RegistryStorage` instance |
+| `getAuthManager()` | Get the shared `AuthManager` instance |
+| `getRegistry(protocol)` | Get a specific protocol handler by name |
+| `isInitialized()` | Check if the registry has been initialized |
+| `destroy()` | Clean up resources |
+
+### Protocol Endpoints
+
+#### OCI Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/{name}/manifests/{ref}` | Get manifest by tag or digest |
+| `PUT` | `/{name}/manifests/{ref}` | Push manifest |
+| `GET` | `/{name}/blobs/{digest}` | Get blob |
+| `POST` | `/{name}/blobs/uploads/` | Initiate blob upload |
+| `PUT` | `/{name}/blobs/uploads/{uuid}` | Complete blob upload |
+| `GET` | `/{name}/tags/list` | List tags |
+| `GET` | `/{name}/referrers/{digest}` | Get referrers (OCI 1.1) |
+
+#### NPM Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/{package}` | Get package metadata (packument) |
+| `PUT` | `/{package}` | Publish package |
+| `GET` | `/{package}/-/{tarball}` | Download tarball |
+| `GET` | `/-/v1/search?text=...` | Search packages |
+| `PUT` | `/-/user/org.couchdb.user:{user}` | Login |
+| `GET/POST/DELETE` | `/-/npm/v1/tokens` | Token management |
+| `PUT` | `/-/package/{pkg}/dist-tags/{tag}` | Manage dist-tags |
+
+#### Maven Repository
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `PUT` | `/{group}/{artifact}/{version}/{file}` | Upload artifact |
+| `GET` | `/{group}/{artifact}/{version}/{file}` | Download artifact |
+| `GET` | `/{group}/{artifact}/maven-metadata.xml` | Get metadata |
+
+#### Cargo Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/config.json` | Registry configuration |
+| `GET` | `/{p1}/{p2}/{name}` | Sparse index entry |
+| `PUT` | `/api/v1/crates/new` | Publish crate (binary format) |
+| `GET` | `/api/v1/crates/{crate}/{version}/download` | Download .crate |
+| `DELETE` | `/api/v1/crates/{crate}/{version}/yank` | Yank version |
+| `PUT` | `/api/v1/crates/{crate}/{version}/unyank` | Unyank version |
+| `GET` | `/api/v1/crates?q=...` | Search crates |
+
+#### Composer Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/packages.json` | Repository metadata |
+| `GET` | `/p2/{vendor}/{package}.json` | Package version metadata |
+| `GET` | `/packages/list.json` | List all packages |
+| `GET` | `/dists/{vendor}/{package}/{ref}.zip` | Download package ZIP |
+| `PUT` | `/packages/{vendor}/{package}` | Upload package |
+| `DELETE` | `/packages/{vendor}/{package}[/{version}]` | Delete package/version |
+
+#### PyPI Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/simple/` | List all packages (PEP 503/691) |
+| `GET` | `/simple/{package}/` | List package files |
+| `POST` | `/` | Upload package (multipart) |
+| `GET` | `/pypi/{package}/json` | Package metadata API |
+| `GET` | `/pypi/{package}/{version}/json` | Version metadata |
+| `GET` | `/packages/{package}/{filename}` | Download file |
+
+#### RubyGems Registry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/versions` | Master versions file (compact index) |
+| `GET` | `/info/{gem}` | Gem info file |
+| `GET` | `/names` | List all gem names |
+| `POST` | `/api/v1/gems` | Upload .gem file |
+| `DELETE` | `/api/v1/gems/yank` | Yank version |
+| `PUT` | `/api/v1/gems/unyank` | Unyank version |
+| `GET` | `/api/v1/versions/{gem}.json` | Version metadata |
+| `GET` | `/gems/{gem}-{version}.gem` | Download .gem file |
+
+## 🎯 Scope Format
+
+Unified scope format across all protocols:
+
+```
+{protocol}:{type}:{name}:{action}
+
+Examples:
+  npm:package:express:read          # Read express package
+  npm:package:*:write               # Write any package
+  oci:repository:nginx:pull         # Pull nginx image
+  oci:repository:*:push             # Push any image
+  cargo:crate:serde:write           # Write serde crate
+  composer:package:vendor/pkg:read  # Read Composer package
+  pypi:package:requests:read        # Read PyPI package
+  rubygems:gem:rails:write          # Write RubyGems gem
+  {protocol}:*:*:*                  # Full access for a protocol
+```
 
 ## 🗄️ Storage Structure
 
 ```
 bucket/
 ├── oci/
-│   ├── blobs/
-│   │   └── sha256/{hash}
-│   ├── manifests/
-│   │   └── {repository}/{digest}
-│   └── tags/
-│       └── {repository}/tags.json
+│   ├── blobs/sha256/{hash}
+│   ├── manifests/{repository}/{digest}
+│   └── tags/{repository}/tags.json
 ├── npm/
-│   ├── packages/
-│   │   ├── {name}/
-│   │   │   ├── index.json          # Packument
-│   │   │   └── {name}-{ver}.tgz    # Tarball
-│   │   └── @{scope}/{name}/
-│   │       ├── index.json
-│   │       └── {name}-{ver}.tgz
-│   └── users/
-│       └── {username}.json
+│   └── packages/{name}/
+│       ├── index.json              # Packument
+│       └── {name}-{ver}.tgz       # Tarball
 ├── maven/
-│   ├── artifacts/
-│   │   └── {group-path}/{artifact}/{version}/
-│   │       ├── {artifact}-{version}.jar
-│   │       ├── {artifact}-{version}.pom
-│   │       └── {artifact}-{version}.{ext}
-│   └── metadata/
-│       └── {group-path}/{artifact}/maven-metadata.xml
+│   ├── artifacts/{group}/{artifact}/{version}/
+│   └── metadata/{group}/{artifact}/maven-metadata.xml
 ├── cargo/
-│   ├── config.json                 # Registry configuration (sparse protocol)
-│   ├── index/                      # Hierarchical index structure
-│   │   ├── 1/{name}               # 1-char crate names (e.g., "a")
-│   │   ├── 2/{name}               # 2-char crate names (e.g., "io")
-│   │   ├── 3/{c}/{name}           # 3-char crate names (e.g., "3/a/axo")
-│   │   └── {p1}/{p2}/{name}       # 4+ char (e.g., "se/rd/serde")
-│   └── crates/
-│       └── {name}/{name}-{version}.crate  # Gzipped tar archives
+│   ├── config.json
+│   ├── index/{p1}/{p2}/{name}     # Sparse index
+│   └── crates/{name}/{name}-{ver}.crate
 ├── composer/
-│   └── packages/
-│       └── {vendor}/{package}/
-│           ├── metadata.json       # All versions metadata
-│           └── {reference}.zip     # Package ZIP files
+│   └── packages/{vendor}/{package}/
+│       ├── metadata.json
+│       └── {reference}.zip
 ├── pypi/
-│   ├── simple/                     # PEP 503 HTML files
-│   │   ├── index.html              # All packages list
-│   │   └── {package}/index.html   # Package versions list
-│   ├── packages/
-│   │   └── {package}/{filename}   # .whl and .tar.gz files
-│   └── metadata/
-│       └── {package}/metadata.json # Package metadata
+│   ├── simple/index.html
+│   ├── simple/{package}/index.html
+│   ├── packages/{package}/{filename}
+│   └── metadata/{package}/metadata.json
 └── rubygems/
-    ├── versions                    # Master versions file
-    ├── info/{gemname}              # Per-gem info files
-    ├── names                       # All gem names
-    └── gems/{gemname}-{version}.gem # .gem files
+    ├── versions
+    ├── info/{gemname}
+    ├── names
+    └── gems/{gemname}-{version}.gem
 ```
 
-## 🎯 Scope Format
+## 🌊 Streaming Architecture
 
-Unified scope format across protocols:
+All responses from `SmartRegistry.handleRequest()` use the **Web Streams API**. The `body` field on `IResponse` is always a `ReadableStream<Uint8Array>` — whether the content is a 2GB container image layer or a tiny JSON metadata response.
 
-```
-{protocol}:{type}:{name}:{action}
+### How It Works
 
-Examples:
-  npm:package:express:read          # Read express package
-  npm:package:*:write               # Write any package
-  npm:*:*:*                         # Full NPM access
+- **Binary downloads** (blobs, tarballs, .crate, .zip, .whl, .gem) stream directly from S3 to the response — zero buffering in memory
+- **JSON/metadata responses** are automatically wrapped into a `ReadableStream` at the API boundary
+- **OCI chunked uploads** store each PATCH chunk as a temp S3 object instead of accumulating in memory, then stream-assemble during the final PUT with incremental SHA-256 verification
 
-  oci:repository:nginx:pull         # Pull nginx image
-  oci:repository:*:push             # Push any image
-  oci:*:*:*                         # Full OCI access
+### Stream Helpers
 
-  maven:artifact:com.example:read   # Read Maven artifact
-  maven:artifact:*:write            # Write any artifact
-  maven:*:*:*                       # Full Maven access
-
-  cargo:crate:serde:write           # Write serde crate
-  cargo:crate:*:read                # Read any crate
-  cargo:*:*:*                       # Full Cargo access
+```typescript
+import { streamToBuffer, streamToJson, toReadableStream } from '@push.rocks/smartregistry';
 
-  composer:package:vendor/package:read   # Read Composer package
-  composer:package:*:write          # Write any package
-  composer:*:*:*                    # Full Composer access
+// Consume a stream into a Buffer
+const buffer = await streamToBuffer(response.body);
 
-  pypi:package:my-package:read      # Read PyPI package
-  pypi:package:*:write              # Write any package
-  pypi:*:*:*                        # Full PyPI access
+// Consume a stream into parsed JSON
+const data = await streamToJson(response.body);
 
-  rubygems:gem:rails:read           # Read RubyGems gem
-  rubygems:gem:*:write              # Write any gem
-  rubygems:*:*:*                    # Full RubyGems access
+// Create a ReadableStream from any data type
+const stream = toReadableStream({ hello: 'world' });
 ```
 
-## 🔌 Integration Examples
+### Consuming in Node.js HTTP Servers
+
+Since Node.js `http.ServerResponse` uses Node streams, bridge with `Readable.fromWeb()`:
+
+```typescript
+import { Readable } from 'stream';
+
+if (response.body) {
+  Readable.fromWeb(response.body).pipe(res);
+} else {
+  res.end();
+}
+```
 
-### Express Server
+## 🔌 Integration with Express
 
 ```typescript
 import express from 'express';
+import { Readable } from 'stream';
 import { SmartRegistry } from '@push.rocks/smartregistry';
 
 const app = express();
@@ -1217,16 +812,13 @@ app.all('*', async (req, res) => {
   });
 
   res.status(response.status);
-  Object.entries(response.headers).forEach(([key, value]) => {
+  for (const [key, value] of Object.entries(response.headers)) {
     res.setHeader(key, value);
-  });
+  }
 
   if (response.body) {
-    if (Buffer.isBuffer(response.body)) {
-      res.send(response.body);
-    } else {
-      res.json(response.body);
-    }
+    // All response bodies are ReadableStream<Uint8Array> — pipe to HTTP response
+    Readable.fromWeb(response.body).pipe(res);
   } else {
     res.end();
   }
@@ -1235,110 +827,60 @@ app.all('*', async (req, res) => {
 app.listen(5000);
 ```
 
-## 🛠️ Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm run build
-
-# Test
-pnpm test
-```
-
-## 🧪 Testing with smarts3
-
-smartregistry works seamlessly with [@push.rocks/smarts3](https://code.foss.global/push.rocks/smarts3), a local S3-compatible server for testing. This allows you to test the registry without needing cloud credentials or external services.
+## 🧪 Testing with smartstorage
 
-### Quick Start with smarts3
+smartregistry works seamlessly with [@push.rocks/smartstorage](https://code.foss.global/push.rocks/smartstorage), a local S3-compatible server for testing — no cloud credentials needed.
 
 ```typescript
-import { Smarts3 } from '@push.rocks/smarts3';
+import { SmartStorage } from '@push.rocks/smartstorage';
 import { SmartRegistry } from '@push.rocks/smartregistry';
 
 // Start local S3 server
-const s3Server = await Smarts3.createAndStart({
-  server: { port: 3456 },
+const s3Server = await SmartStorage.createAndStart({
+  server: { port: 3456, silent: true },
   storage: { cleanSlate: true },
 });
 
-// Manually create IS3Descriptor matching smarts3 configuration
-// Note: smarts3 v5.1.0 doesn't properly expose getS3Descriptor() yet
-const s3Descriptor = {
-  endpoint: 'localhost',
-  port: 3456,
-  accessKey: 'test',
-  accessSecret: 'test',
-  useSsl: false,
-  region: 'us-east-1',
-};
+// Get S3 descriptor from the running server
+const s3Descriptor = await s3Server.getStorageDescriptor();
 
-// Create registry with smarts3 configuration
 const registry = new SmartRegistry({
-  storage: {
-    ...s3Descriptor,
-    bucketName: 'my-test-registry',
-  },
-  auth: {
-    jwtSecret: 'test-secret',
-    tokenStore: 'memory',
-    npmTokens: { enabled: true },
-    ociTokens: {
-      enabled: true,
-      realm: 'https://auth.example.com/token',
-      service: 'my-registry',
-    },
-  },
+  storage: { ...s3Descriptor, bucketName: 'my-test-registry' },
+  auth: { jwtSecret: 'test', tokenStore: 'memory', npmTokens: { enabled: true } },
   npm: { enabled: true, basePath: '/npm' },
   oci: { enabled: true, basePath: '/oci' },
-  pypi: { enabled: true, basePath: '/pypi' },
-  cargo: { enabled: true, basePath: '/cargo' },
 });
-
 await registry.init();
 
-// Use registry...
-// Your tests here
-
-// Cleanup
+// ... run your tests ...
 await s3Server.stop();
 ```
 
-### Benefits of Testing with smarts3
-
-- ✅ **Zero Setup** - No cloud credentials or external services needed
-- ✅ **Fast** - Local filesystem storage, no network latency
-- ✅ **Isolated** - Clean slate per test run, no shared state
-- ✅ **CI/CD Ready** - Works in automated pipelines without configuration
-- ✅ **Full Compatibility** - Implements S3 API, works with IS3Descriptor
-
-### Running Integration Tests
+## 🛠️ Development
 
 ```bash
-# Run smarts3 integration test
-pnpm exec tstest test/test.integration.smarts3.node.ts --verbose
-
-# Run all tests (includes smarts3)
-pnpm test
+pnpm install       # Install dependencies
+pnpm run build     # Build
+pnpm test          # Run all tests
 ```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.