node-auth
A fast, lightweight, standalone Rust CLI and library that authenticates Node package managers (npm, yarn, and pnpm) to private Google Artifact Registry (GAR) npm repositories using Google Cloud Application Default Credentials (ADC).
It replicates and improves upon the functionality of Google's @google-cloud/artifact-registry-npm-tools, but without requiring Node, npm, or pnpm to be installed or configured beforehand.
Why node-auth?
Google's official google-artifactregistry-auth tool is distributed as an npm package. This creates a chicken-and-egg problem:
- In minimal CI/CD containers, Docker build stages, or restricted developer workstations, you often need authentication before Node/npm is bootstrapped or when bootstrapping dependency caches.
- It introduces heavy Node.js runtime dependencies just to write an authentication token to
.npmrc.
node-auth builds native binaries for Windows, Linux, and macOS and does not require a Node.js runtime. Static linking depends on the selected build target.
Platform Support
- Windows: Managed workstations, supports PowerShell and CMD (
%USERPROFILE%,%APPDATA%, andgcloud.cmd). - Linux: CI/CD pipelines (GitHub Actions, GitLab CI, Cloud Build), containers (Debian, Ubuntu, Alpine), and servers.
- macOS: Local development workstations (Apple Silicon & Intel).
How Authentication Works
node-auth searches for credentials in the following order:
- Explicit Token: If
--token <TOKEN>(orNODE_AUTH_TOKEN) is provided, it is used immediately. - Google Application Default Credentials (ADC):
GOOGLE_APPLICATION_CREDENTIALSenvironment variable (Service Account JSON, Workload Identity Federation).- Well-known user credentials created by
gcloud auth application-default login:- Linux/macOS:
$HOME/.config/gcloud/application_default_credentials.json - Windows:
%APPDATA%\gcloud\application_default_credentials.json
- Linux/macOS:
- GCE / Cloud Run / GKE / Cloud Build metadata service (
http://metadata.google.internal).
- gcloud CLI Fallback:
- If ADC is not configured, falls back to
gcloud auth print-access-token(orgcloud.cmdon Windows) for developers logged in viagcloud auth login.
- If ADC is not configured, falls back to
- Actionable Guidance:
- If credentials cannot be found, prints exact setup commands.
Installation
Cargo
This installs both node-auth and the compatibility command
artifactregistry-auth.
Homebrew
Release automation publishes a formula to the tap configured by the maintainer:
Replace OWNER/TAP with the configured tap repository. The generated
node-auth.rb formula is also attached to every GitHub release.
Scoop
Release automation publishes a manifest to the bucket configured by the maintainer:
scoop bucket add node-auth https://github.com/OWNER/BUCKET
scoop install node-auth
Replace OWNER/BUCKET with the configured bucket repository. The generated
node-auth.json manifest is also attached to every GitHub release.
GitHub Releases
Prebuilt archives for Linux x86-64, macOS Intel and Apple Silicon, and Windows
x86-64 are available on the repository's Releases page. Each release includes
a SHA256SUMS file.
From Source
This installs both node-auth and the drop-in alias artifactregistry-auth to ~/.cargo/bin.
Building Release Binaries
# Binaries available in target/release/node-auth and target/release/artifactregistry-auth
Generating API Documentation
You can generate and view the Rustdoc API documentation using cargo:
# Generate documentation without external dependencies
# Generate and open in your default browser
Documentation will be generated at target/doc/node_auth/index.html.
CLI Usage
Basic Usage
Run in your project root:
By default:
- Reads registry configurations from
./.npmrc(or~/.npmrcif no local file exists). - Writes the authentication token to your user-level
~/.npmrc(%USERPROFILE%\.npmrcon Windows) so secret tokens are never accidentally committed to Git. - If
./.yarnrc.ymlexists, also updates Yarn Modern scope credentials.
Writing to Local .npmrc (--local-credential / -l)
In CI/CD jobs or container builds, you often want credentials written directly to the project directory:
When running with --local-credential:
- It writes the token directly to
./.npmrc(creating the file if it doesn't exist). - Git Safety Check:
-
If Git reports
.npmrcas tracked or not ignored, it warns:Warning: Local .npmrc is tracked or not ignored by Git; it may expose credentials if committed. -
If the directory is not a Git repository, it reminds:
Warning: Local .npmrc is outside a Git repository; keep credentials out of version control.
-
Only Print the Access Token (--print-token)
If you just need the token for custom scripts or environment variables:
CLI Options
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
-l, --local-credential |
- | false |
Force writing credentials to ./.npmrc. Checks .gitignore for safety. |
--repo-config <PATH> |
NODE_AUTH_REPO_CONFIG |
./.npmrc or ~/.npmrc |
Path to .npmrc to read registry configs from. |
--credential-config <PATH> |
NODE_AUTH_CREDENTIAL_CONFIG |
~/.npmrc |
Path to .npmrc to write credentials to. |
--repo-config-yarn <PATH> |
- | ./.yarnrc.yml or ~/.yarnrc.yml |
Path to .yarnrc.yml to read scope configurations from. |
--credential-config-yarn <PATH> |
- | ~/.yarnrc.yml |
Path to .yarnrc.yml to write credentials to. |
--yarn <BOOL> |
- | Auto-detect | Explicitly enable (--yarn true) or disable (--yarn false) Yarn updating. |
--token <TOKEN> |
NODE_AUTH_TOKEN |
- | Explicit token to use instead of ADC/gcloud. |
--allow-all-domains |
- | false |
Allow attaching the token to other HTTPS registry domains in both npm and Yarn configuration. |
-v, --verbose |
- | false |
Enable verbose logging output. |
--print-token |
- | false |
Output access token to stdout without modifying config files. |
-h, --help |
- | - | Print help information. |
Configuration Formats Supported
NPM (.npmrc)
Supports standard scoped or unscoped Artifact Registry definitions:
@my-org:registry=https://us-central1-npm.pkg.dev/my-project/my-repo/
node-auth automatically generates or updates the credential line in the target .npmrc:
//us-central1-npm.pkg.dev/my-project/my-repo/:_authToken="ya29.a0AfH6..."
- Replaces legacy basic auth passwords (
:_passwordandusername=oauth2accesstoken). - Strips sensitive
_authTokenentries out of project-level.npmrcwhen writing to user~/.npmrc. - Preserves all other configs, comments, and other registries (e.g.
registry.npmjs.org).
Yarn Modern (.yarnrc.yml)
If .yarnrc.yml is used:
npmScopes:
my-org:
npmRegistryServer: "https://us-central1-npm.pkg.dev/my-project/my-repo"
node-auth adds or updates:
npmScopes:
my-org:
npmRegistryServer: "https://us-central1-npm.pkg.dev/my-project/my-repo"
npmAlwaysAuth: true
npmAuthToken: "ya29.a0AfH6..."
Registry URLs must use HTTPS and may not contain embedded credentials, queries, or fragments. By default, only Artifact Registry hosts ending in -npm.pkg.dev receive a token; other Yarn scopes are left unchanged. --allow-all-domains explicitly permits other HTTPS hosts. Malformed Yarn YAML causes an error without replacing either rc file.
File Updates and Library Use
Before reading, paths are resolved to absolute paths, including symlink targets. The tool locks the affected files during a run, stages all changes in temporary files beside their destinations, and replaces each file atomically. New credential files are created with owner-only permissions (0600) on Unix and a protected, current-user-only DACL on Windows. Existing Unix mode bits and Windows DACLs are preserved during replacement. The tool does not audit or repair permissions on files created by other applications.
The locking files (for example, .npmrc.node-auth.lock) remain beside the rc files so concurrent runs can coordinate. They contain no credentials. If using local credentials, add *.node-auth.lock to your project .gitignore as desired. Replacing multiple rc files is not one filesystem-wide atomic operation; interruption between replacements can leave a partial update.
The Rust library returns Result<RunOutcome, AuthError> from run(&Options). The outcome contains either a token for print_token or the paths updated and the local Git safety status. The library does not initialize a logger or print terminal messages; the CLI handles those results.
Maintainer Releases
CI runs formatting, lint, packaging, and tests on every pull request and push to
main. Tests run on current GitHub-hosted Linux, macOS, and Windows runners.
To publish a release:
- Update
versioninCargo.toml, updateCargo.lock, and merge the change. - Create and push the matching tag, for example
v0.2.0. - Approve the protected
releaseenvironment if repository rules require it.
The release workflow publishes the crate, creates native archives and checksums, creates the GitHub release, and renders Homebrew and Scoop package definitions. Configure the repository with:
- A
releaseGitHub Actions environment, preferably restricted to protected tags and requiring approval. - The
CARGO_REGISTRY_TOKENenvironment secret with permission to publish thenode-authcrate. - Optional
HOMEBREW_TAP_REPOSITORYandSCOOP_BUCKET_REPOSITORYrepository variables, each inowner/repositoryform. - Optional
PACKAGE_REPOSITORY_TOKENenvironment secret with Contents write access to those package repositories. It is required when either repository variable is configured.
The Homebrew repository should use the conventional homebrew-TAP name. The
workflow writes Formula/node-auth.rb. The Scoop repository receives
node-auth.json at its root. If those repositories are not configured, the
formula and manifest remain available as GitHub release assets.
License
Licensed under the Apache License, Version 2.0.