Skip to content

Latest commit

 

History

History
350 lines (282 loc) · 8.85 KB

README.md

File metadata and controls

350 lines (282 loc) · 8.85 KB
Raw

vlt serverless registry (vsr)

vsr 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.

vsr api screenshot

Table of Contents:

Quick Starts

Local

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

npx -y vltpkg/vsr

Production

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

Deply to Cloudflare Workers

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

Development

# clone the repo
git clone https://github.com/vltpkg/vsr.git

# navigate to the repository directory
cd ./vsr

# 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
Scope Examples
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 vsr locally (ex. run npx -y vltpkg/vsr &/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. vlt, yarn, pnpm & bun)

Configuration

To use vsr 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 vsr 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).