CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-verdaccio

A lightweight private npm proxy registry application with comprehensive package management, authentication, and web interface capabilities

—

Pending
Overview
Eval results
Files

http-api.mddocs/

HTTP Registry API

RESTful API implementing npm registry protocol for package publishing, installation, and management. The HTTP API provides all standard npm registry operations plus Verdaccio-specific features.

Capabilities

Package Management

Core package CRUD operations following npm registry protocol.

// Package metadata retrieval
app.get('/:package', packageHandler);
app.get('/:package/:version', packageVersionHandler);

// Package publishing and updates
app.put('/:package/:_rev?/:revision?', publishHandler);
app.put('/:package/-rev/:revision', updatePackageHandler);

// Package deletion
app.delete('/:package/-rev/*', unpublishHandler);
app.delete('/:package/-/:filename/-rev/:revision', removeTarballHandler);

// Tarball operations
app.get('/:package/-/:filename', downloadTarballHandler);
app.put('/:package/-/:filename/*', uploadPackageTarballHandler);

// Debug endpoints (development only)
app.put('/:package/:version/-tag/:tag', addVersionHandler);

Usage Examples:

# Get package metadata
curl http://localhost:4873/express

# Get specific version
curl http://localhost:4873/express/4.18.2

# Publish package (requires authentication)
npm publish --registry http://localhost:4873

# Download tarball
curl http://localhost:4873/express/-/express-4.18.2.tgz

User Management & Authentication

User registration, authentication, and profile management.

// User authentication
app.put('/-/user/:user', userHandler);
app.post('/-/user/:user', userLoginHandler);

// Current user info
app.get('/-/whoami', whoamiHandler);

// User profile (v1 API)
app.get('/-/npm/v1/user', profileHandler);
app.post('/-/npm/v1/user', updateProfileHandler);

// Token management (v1 API)
app.post('/-/npm/v1/tokens', createTokenHandler);
app.get('/-/npm/v1/tokens', listTokensHandler);
app.delete('/-/npm/v1/tokens/token/:tokenKey', deleteTokenHandler);

Usage Examples:

# Create user / login
npm adduser --registry http://localhost:4873

# Check current user
npm whoami --registry http://localhost:4873

# Create authentication token
curl -X POST http://localhost:4873/-/npm/v1/tokens \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"password":"<password>","readonly":false,"cidr_whitelist":[]}'

Distribution Tags

Package version tag management (latest, beta, alpha, etc.).

// Get all dist-tags for package
app.get('/-/package/:package/dist-tags', distTagsListHandler);

// Get specific dist-tag version
app.get('/:package/:tag', distTagHandler);

// Update/create dist-tag
app.put('/-/package/:package/dist-tags/:tag', tagPackageVersionHandler);
app.post('/-/package/:package/dist-tags/:tag', tagPackageVersionHandler);
app.post('/-/package/:package/dist-tags', updateMultipleTagsHandler);

// Delete dist-tag
app.delete('/-/package/:package/dist-tags/:tag', deleteDistTagHandler);

Usage Examples:

# Get all tags for package
curl http://localhost:4873/express/-/tags

# Set dist-tag
npm dist-tag add express@4.18.2 stable --registry http://localhost:4873

# Remove dist-tag
npm dist-tag rm express stable --registry http://localhost:4873

Search & Discovery

Package search and discovery functionality.

// Legacy search (deprecated)
app.get('/-/all', allPackagesHandler);
app.get('/-/all/since', allPackagesSinceHandler);

// Modern search (v1 API)
app.get('/-/v1/search', searchHandler);

// Package stars/favorites
app.get('/-/_view/starredByUser', starredByUserHandler);
app.put('/:package/-/_star', starPackageHandler);
app.delete('/:package/-/_star', unstarPackageHandler);

Usage Examples:

# Search packages
curl "http://localhost:4873/-/v1/search?text=express&size=20"

# Get all packages
curl http://localhost:4873/-/all

# Star a package
curl -X PUT http://localhost:4873/express/-/_star \
  -H "Authorization: Bearer <token>"

System Operations

Health checks and system status information.

// Health check / ping
app.get('/-/ping', pingHandler);

// Current user info
app.get('/-/whoami', whoamiHandler);

NPM v1 Profile API

Modern npm profile management endpoints.

// Get user profile
app.get('/-/npm/v1/user', profileHandler);

// Update user profile
app.post('/-/npm/v1/user', updateProfileHandler);

NPM v1 Token Management

Authentication token management for modern npm clients.

// List user tokens
app.get('/-/npm/v1/tokens', listTokensHandler);

// Create new token
app.post('/-/npm/v1/tokens', createTokenHandler);

// Delete specific token
app.delete('/-/npm/v1/tokens/token/:tokenKey', deleteTokenHandler);

Web UI API

Verdaccio web interface endpoints for package browsing and management.

// Web UI package management
app.get('/-/verdaccio/data/packages', webPackageListHandler);
app.get('/-/verdaccio/data/sidebar/:scope/:package', webSidebarHandler);
app.get('/-/verdaccio/data/sidebar/:package', webSidebarHandler);
app.get('/-/verdaccio/data/readme/:scope/:package/:version', webReadmeHandler);
app.get('/-/verdaccio/data/readme/:package/:version', webReadmeHandler);

// Web UI search
app.get('/-/verdaccio/data/search/:anything', webSearchHandler);

// Web UI authentication
app.post('/-/verdaccio/sec/login', webLoginHandler);
app.put('/-/verdaccio/sec/reset_password', webPasswordResetHandler);

// Static assets
app.get('/-/static/favicon.ico', serveFaviconHandler);

Usage Examples:

# Health check
curl http://localhost:4873/-/ping

# Check current user
curl http://localhost:4873/-/whoami

# Get package list for web UI
curl http://localhost:4873/-/verdaccio/data/packages

Authentication

The API supports multiple authentication methods:

Bearer Token Authentication

curl -H "Authorization: Bearer <token>" http://localhost:4873/package

Basic Authentication

curl -u username:password http://localhost:4873/package

JWT Middleware

Internal JWT middleware for session management and token validation.

Request/Response Format

Standard Headers

  • Content-Type: application/json for JSON payloads
  • User-Agent: npm/<version> for npm client compatibility
  • Authorization: Bearer <token> for authenticated requests

Error Responses

interface ErrorResponse {
  error: string;
  reason?: string;
}

Common HTTP status codes:

  • 200: Success
  • 201: Created (package published)
  • 400: Bad Request (invalid data)
  • 401: Unauthorized (authentication required)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found (package/version doesn't exist)
  • 409: Conflict (package already exists)
  • 500: Internal Server Error

Package Metadata Format

interface PackageMetadata {
  _id: string;
  name: string;
  description?: string;
  "dist-tags": { [tag: string]: string };
  versions: { [version: string]: VersionMetadata };
  time: { [version: string]: string };
  author?: Person;
  contributors?: Person[];
  repository?: Repository;
  keywords?: string[];
  license?: string;
}

interface VersionMetadata {
  name: string;
  version: string;
  description?: string;
  main?: string;
  types?: string;
  dependencies?: Dependencies;
  devDependencies?: Dependencies;
  peerDependencies?: Dependencies;
  dist: {
    tarball: string;
    shasum: string;
    integrity?: string;
  };
}

Rate Limiting

Verdaccio supports configurable rate limiting for API endpoints:

  • Per-IP request limits
  • Authentication-based limits
  • Configurable time windows

CORS Support

Cross-Origin Resource Sharing (CORS) is enabled by default for web interface compatibility.

Proxy Behavior

When packages are not found locally, Verdaccio can proxy requests to upstream registries based on configuration:

  • Transparent proxying to npmjs.org or other registries
  • Caching of downloaded packages
  • Fallback behavior for missing packages

Install with Tessl CLI

npx tessl i tessl/npm-verdaccio

docs

cli.md

configuration.md

http-api.md

index.md

server-management.md

utilities.md

tile.json