khulnasoft serverless registry (xvn)

xvn aims to be a minimal "npm-compatible" registry which replicates the core features found in registry.npmjs.org as well as adding net-new capabilities.

Table of Contents:

• Quick Starts
• Requirements
• API
• Compatibility
• Comparisons
• Roadmap
• License

Quick Starts

Local

You can quickly get started by installing/executing xvn with the following command:

npx -y xvn

Production

You can deploy xvn to Cloudflare in under 5 minutes, for free, with a single click (coming soon).

Alternatively, you can deploy to production using wrangler after following the Development quick start steps.

Development

# clone the repo
git clone https://github.com/khulnasoft/xvn.git

# navigate to the repository directory
cd ./xvn

# install the project's dependencies
npm install

# run tbe development script
npm run dev

Requirements

Production

• Cloudflare (free account at minimum)
  • Workers (free: 100k requests /day)
  • D1 Database (free: 100k writes, 5M reads /day & 5GB Storage /mo)
  • R2 Bucket (free: 1M writes, 10M reads & 10GB /mo)

Note: all usage numbers & pricing documented is as of October 24th, 2024. Plans & metering is subject to change at Cloudflare's discretion.

Development

• git
• node
• npm

Granular Access Tokens

All tokens are considered "granular access tokens" (GATs). Token entries in the database consist of 3 parts:

• token the unique token value
• uuid associative value representing a single user/scope
• scope value representing the granular access/privileges

scope as a JSON Object

A scope contains an array of privileges that define both the type(s) of & access value(s) for a token.

[!NOTE] Tokens can be associated with multiple "types" of access

• type(s):
  • pkg:read read associated packages
  • pkg:read+write write associated packages (requires read access)
  • user:read read associated user
  • user:read+write write associated user (requires read access)
• value(s):
  • * an ANY selector for user: or pkg: access types
  • ~<user> user selector for the user: access type
  • @<scope>/<pkg> package specific selector for the pkg: access type
  • @<scope>/* glob scope selector for pkg: access types

[!NOTE]

• user/org/team management via @<scope> is not supported at the moment

End-user/Subscriber Persona

• specific package read access
• individual user read+write access

[
  {
    "values": ["@organization/package-name"],
    "types": {
      "pkg": {
        "read": true,
      }
    }
  },
  {
    "values": ["~johnsmith"],
    "types": {
      "user": {
        "read": true,
        "write": true,
      }
    }
  }
]

Team Member/Maintainer Persona

• scoped package read+write access
• individual user read+write access

[
  {
    "values": ["@organization/*"],
    "types": {
      "pkg": {
        "read": true
      }
    }
  },
  {
    "values": ["~johnsmith"],
    "types": {
      "user": {
        "read": true,
        "write": true,
      }
    }
  }
]

Package Publish CI Persona

• organization scoped packages read+write access
• individual user read+write access

[
  {
    "values": ["@organization/package-name"],
    "types": {
      "pkg": {
        "read": true
      }
    }
  },
  {
    "values": ["~johnsmith"],
    "types": {
      "user": {
        "read": true,
        "write": true,
      }
    }
  }
]

Organization Admin Persona

• organization scoped package read+write access
• organization users read+write access

[
  {
    "values": ["@company/*"],
    "types": {
      "pkg": {
        "read": true,
        "write": true
      },
      "user": {
        "read": true,
        "write": true
      }
    }
  }
]

Registry Owner/Admin Persona

[
  {
    "values": ["*"],
    "types": {
      "pkg": {
        "read": true,
        "write": true
      },
      {
        "user": {
          "read": true,
          "write": true
        }
      }
    }
  }
]

API

We have rich, interactive API docs out-of-the-box with the help of our friends Scalar. The docs can be found at the registry root when running xvn locally (ex. run npx -y xvn &/or check out this repo & run npm run dev)

npm Client Compatibility

The following commands should work out-of-the-box with npm & any other npm "compatible" clients although their specific commands & arguments may vary (ex. khulnasoft, yarn, pnpm & bun)

Configuration

To use xvn as your registry you must either pass a registry config through a client-specific flag (ex. --registry=... for npm) or define client-specific configuration which stores the reference to your registry (ex. .npmrc for npm). Access to the registry & packages is private by default although an "admin" user is created during setup locally (for development purposes) with a default auth token of "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

; .npmrc
registry=http://localhost:1337
//localhost:1337/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Supported npm Commands

• ✅ implemented
• ⏳ in progress
• 🕤 planned to support

| Support | Commannd | | :--: | :-- | | ✅ | access | | ✅ | access list packages | | ✅ | access get status | | ❌ | access set status | | ❌ | access set mfa | | ❌ | access grant | | ❌ | access revoke | | 🕤 | adduser - PUT /-/org/@<org>/<user>: Adds/updates a user (requires admin privileges) | | ❌ | audit | | ✅ | bugs | | ❌ | dist-tag add | | ❌ | dist-tag rm | | ❌ | dist-tag ls | | ✅ | deprecate | | ✅ | docs | | ✅ | exec | | ❌ | hook | | ✅ | install | | ❌ | login | | ❌ | logout | | ❌ | org | | ✅ | outdated | | ❌ | owner add | | ❌ | owner rm | | ❌ | owner ls | | ✅ | ping | | ❌ | profile enable-2fa | | ❌ | profile disable-2fa | | ✅ | profile get | | 🕤 | profile set - PUT /-/npm/v1/user: Updates a user (requires auth) | | ✅ | publish | | ✅ | repo | | ❌ | search | | ❌ | star | | ❌ | team | | ✅ | view | | ✅ | whoami |

• ✅ supported
• ❌ unsupported

Comparisons

| Feature | xvn | verdaccio | jsr | | -- | :-: | :-: | :-: | | Serverless | ✅ | ❌ | ❌ | | JavaScript Backend | ✅ | ✅ | ❌ | | Granular Access/Permissions | ✅ | ✅ | ❌ | | Proxy Upstream Registries | ⏳ | ✅ | ❌ | | Unscoped Package Names | ✅ | ✅ | ❌ | | npm Package Publishing | ✅ | ✅ | ❌ | | npm Package Installation | ✅ | ✅ | ✅* | | CDN | 🕤 | ❌ | ✅ | | ESM | 🕤 | ❌ | ✅ | | Manifest Validation | ✅ | ❌ | ❌ | | Plugins | ⏳ | ✅ | ❌ | | Events/Hooks | 🕤 | ✅ | ❌ | | Programmatic API | ❌ | ✅ | ❌ | | Web Interface | 🕤 | ✅ | ✅ | | Search | 🕤 | ✅ | ✅ | | First-Class Typescript | ❌ | ❌ | ✅ | | API Documentation Generation | ❌ | ❌ | ✅ | | Multi-Cloud | 🕤 | ✅ | ✅ | | Azure DevOps Artifacts Upstream | ✅ | ✅ | ✅ | | JFrog Artifactory Upstream | ✅ | ✅ | ❌ | | Google Artifact Registry Upstream | ✅ | ✅ | ❌ |

* requires jsr-specific tooling or use a modified package name when using traditional npm clients (ref. https://jsr.io/docs/npm-compatibility)

Roadmap

| Status | Feature | | :--: | :-- | | ✅ | api: minimal package metadata | | ✅ | api: full package manifests | | ✅ | api: publishing private, scoped packages | | ✅ | api: package manifest validation | | ✅ | api: admin user management (add/update/remove users) | | ✅ | api: user token management (add/update/remove tokens) | | ✅ | web: docs portal | | ✅ | api: unscoped packages | | ⏳ | web & api: custom dist-tags (latest is supported) | | ⏳ | web & api: token rate-limiting | | 🕤 | web & api: search | | 🕤 | web & api: staging | | 🕤 | web: admin user management | | 🕤 | web: user registration | | 🕤 | web: user login (ex. npm login / --auth-type=web) | | 🕤 | web: user account management |

License

This project is licensed under the Functional Source License (FSL-1.1-MIT).