Verdaccio Plugin DB

A powerful SQLite-backed plugin to manage users, groups, and fine-grained package access in Verdaccio. This plugin includes a complete interactive CLI for all operations, making it easy to control who can access, publish, or unpublish packages in your private registry.

Features

• User & Group Management: Add, update, and remove users and groups.
• Fine-Grained Access Control: Assign package-level actions (access, publish, unpublish, etc.) to groups for any package scope.
• Menu-Driven CLI: Navigate an interactive menu to manage users, groups, package scopes, and access permissions.
• Self-contained: All data is stored in a single SQLite file, no external DB server required.
• Easy Verdaccio Integration: Just configure the plugin and point it to your database file.

Table of Contents

• Installation

• How It Works

• Usage - CLI

  • How to Start the CLI
  • Menu Structure
  • User Commands
  • Group Commands
  • Package Commands
  • Database Management

• Integrating with Verdaccio

• Configuration

• Development

• License

Installation

1. Place this plugin in your Verdaccio plugins folder or clone this repository.

2. Install dependencies:

   npm install

3. (Optional) Build TypeScript:

   npm run build

How It Works

This plugin manages all authentication, groups, and access permissions in an SQLite database. Every user, group, package scope, and access rule is stored and can be managed using the provided CLI.

Schema:

• user: User accounts with hashed passwords.
• group: Named groups for organizing permissions.
• user_group: Links users to groups.
• package_access: Package scopes (supports wildcards like @*/*, **, etc.).
• package_action: Actions available for packages.
• package_access_group: Defines which group has which action on which package scope.

Usage - CLI

How to Start the CLI

You can use the CLI in two ways:

1. Running directly with Node

node cli.js <path-to-your-db-file>

Example:

node cli.js ./verdaccio-auth.db

2. Installing globally and using as a command

After publishing or linking the package globally, you can run:

npm install -g verdaccio-auth-db
verdaccio-auth-db <path-to-your-db-file>

Example:

verdaccio-auth-db ./verdaccio-auth.db

If the database file does not exist, it will be created and seeded with initial users, groups, and permissions.

Menu Structure

You will be greeted by the Main Menu:

==== MAIN MENU ====
1 - Manage users
2 - Manage groups
3 - Manage packages
4 - Recreate database (WARNING: This will delete all data)
5 - Show help
0 - Exit

Navigate using the menu numbers.

User Commands

Within "Manage users":

• 1 - List users
• 2 - Add user
• 3 - Update user password
• 4 - Delete user
• 0 - Back

Group Commands

Within "Manage groups":

• 1 - List groups
• 2 - Add group
• 3 - Update group
• 4 - Delete group
• 5 - Add user to group
• 6 - Remove user from group
• 0 - Back

Package Commands

Within "Manage packages":

• 1 - List package scopes
• 2 - Add package scope
• 3 - Update package scope
• 4 - Delete package scope
• 5 - Add group/action to package
• 6 - Remove group/action from package
• 0 - Back

Supported actions: access, publish, unpublish

Database Management

• Option 4 in the main menu: Recreate database (WARNING: This will delete all data)

  • This will drop and recreate the database with the default structure and initial data.

Integrating with Verdaccio

1. Build the plugin if necessary:

   npm run build

2. Copy your SQLite database file and this plugin to your Verdaccio server or plugins folder.

3. Edit your config.yaml in Verdaccio:

   auth:
     auth-db:
       path: ./verdaccio-auth.db

   • Replace auth-db with your plugin name if you changed it.
   • Make sure the path to your .db file is correct.

4. Restart Verdaccio.

   • The plugin will now control all authentication and access logic.

Configuration

• You do not need to set environment variables.
• Pass the database file location as an argument when running the CLI.
• If running as a plugin, Verdaccio will use the path you set in config.yaml.

Development

• Written in TypeScript.
• Uses better-sqlite3 for SQLite access.
• Modular code, easy to extend.
• PRs and contributions are welcome!

License

MIT

Have questions or need help? Open an issue or pull request on the repository!