npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@mercury-fw/plugin-zitadel

v0.6.0

Published

Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent read access to a [ZITADEL](https://zitadel.com) instance through the `zitadel` CLI: users (searched by email or username, or read by id), their project roles and identity provider links, org

Readme

@mercury-fw/plugin-zitadel

Gives a Mercury agent read access to a ZITADEL instance through the zitadel CLI: users (searched by email or username, or read by id), their project roles and identity provider links, organizations and projects. The pinned binary downloads when the package installs. This version is written for version 7 of the plugin contract and needs the framework at 0.75 or later: an older core skips it, and the log says why.

On Mercury's documentation site: its page.

bun add @mercury-fw/plugin-zitadel

In the app: list it in trustedDependencies (or Bun skips the install script that downloads the binary) and declare it in mercury.config.ts:

import { zitadelPlugin } from "@mercury-fw/plugin-zitadel";

plugins: [zitadelPlugin],

Nothing it runs changes ZITADEL. Administrative commands come with the CLI's, and the destructive ones will ask for confirmation.

Credentials

The plugin acts as the person: every command runs with the ZITADEL account of whoever Mercury is talking to, so ZITADEL decides what they can read. On the terminal (mfw repl) there's no person, and commands run as the instance's service user.

The CLI keeps every login under ~/.config/zitadel-cli (one folder per person, next to the service user's), and the plugin declares that folder in its package.json (mercury.cliCredentials) with the commands that set it up. Two things are set up once, inside the app's container, answering what the CLI asks (the zitadel CLI's README has the steps on ZITADEL's side):

  • the service user the terminal runs as: the CLI asks for the instance URL and the service user's key JSON, pasted whole (hidden). ORG_OWNER_VIEWER on the organization is enough to read users, their project roles and their identity provider links;
  • the Native app people log in through, with <HTTP_SURFACE_PUBLIC_URL>/login/callback among its redirect URIs: the CLI asks for its client id.

ZITADEL's guides for both: Private key JWT for service accounts (the key JSON) and Applications (the Native app).

mfw credentials setup @mercury-fw/plugin-zitadel
mfw credentials setup @mercury-fw/plugin-zitadel --user-app
mfw credentials check @mercury-fw/plugin-zitadel

As the user directory

The same package exports zitadelDirectory: ZITADEL decides who the people talking to Mercury are and what they may make it do, through the project's roles. Declare it next to the OIDC auth provider pointing at the same ZITADEL:

import { zitadelPlugin, zitadelDirectory } from "@mercury-fw/plugin-zitadel";
import { oidcAuth } from "@mercury-fw/auth-oidc";

auth: oidcAuth,
directory: zitadelDirectory,

| Variable | | |---|---| | ZITADEL_PROJECT_ID | Required. The project whose roles count (zitadel project list --select projects.projectId,projects.name lists them). | | ZITADEL_GOOGLE_IDP_ID | Optional. The id ZITADEL gives the Google identity provider; zitadel user idp-links <your user id> --select result.idpId,result.idpName shows it for someone who signed in with Google. Without it, nobody is recognised from Google Chat. | | ZITADEL_AUTH_PROVIDER | Optional. The auth provider whose tokens come from this ZITADEL, when the instance accepts several issuers: oidc-<name> for createOidcAuth({ name }) (default oidc, the unnamed one). Another provider's people aren't looked up here. |

It calls the CLI from code, never through the model, as the service user set up above, which only needs ORG_OWNER_VIEWER for this. Someone calling the HTTP surface with a token from this ZITADEL's auth provider is the ZITADEL user the token's subject names: unknown (and refused, the instance being closed) when ZITADEL doesn't find them or they aren't active, otherwise known with the role keys of their active role assignments on the project. Their email is passed on only when ZITADEL verified it, and their key is zitadel:<user id>.

The roles that mean something to Mercury are mercury.act-as-self (make Mercury act with its own identity, on every plugin) and mercury.act-as-self.<plugin> (on one), and mercury.context-admin (change the instance's context while it runs); create them as roles of the project and assign them to people in ZITADEL's console (the user's Role Assignments). Any other role is for the app's access.plugins. An answer is kept for five minutes, so a role taken away stops counting within that time.

A Google Chat sender is the ZITADEL user with the sender's email, as long as exactly one user has it (an inactive duplicate is enough to leave them unknown), active, verified, and that user's links to the Google identity provider (ZITADEL_GOOGLE_IDP_ID) include the sender's own Google account (Chat's users/<id> is the id ZITADEL stores for a Google link). The email alone is only the sender saying who they are; the link is ZITADEL confirming it's the same Google account. This needs Google set up as an identity provider in ZITADEL, and people having signed in through it at least once. Anyone else on Chat is unknown to this directory, and can link their Chat account to the one Mercury knows with a code (see the HTTP channel's POST /link).

Identities from other channels aren't resolved by this directory.

People log in on their own: the first time someone asks for something in ZITADEL, Mercury answers that they need to log in, and the HTTP channel shows them the link (it needs HTTP_SURFACE_PUBLIC_URL). Mercury never falls back to the service user for them.

MIT