Secure Credential Storage
Relevant source files
The following files were used as context for generating this wiki page:
Secure Credential Storage in pubm is a multi-layered system designed to handle sensitive authentication tokens for various package registries (npm, jsr, crates.io) and GitHub. The system prioritizes security by utilizing native operating system capabilities while providing robust fallbacks for different environments like CI/CD pipelines.
The primary goal of this system is to ensure that registry tokens are never stored in plain text on the local filesystem. By integrating with native keychains and providing encrypted local storage, pubm allows developers to publish to multiple registries without repeatedly entering credentials or risking token exposure.
Sources: README.md:104-108, README.zh-cn.md:112-116
Architecture and Storage Mechanisms
The storage architecture is hierarchical, selecting the most secure available method based on the operating system and execution environment.
Multi-Layered Storage Strategy
| Storage Layer | Platform/Environment | Description |
|---|---|---|
| Environment Variables | All (Highest Priority) | Tokens like GITHUB_TOKEN, NODE_AUTH_TOKEN, JSR_TOKEN, and CARGO_REGISTRY_TOKEN are read directly from the environment. |
| Native Keychain | macOS, Windows, Linux | Utilizes @napi-rs/keyring to store tokens in the macOS Keychain, Windows Credential Manager, or Linux Secret Service. |
| Encrypted Local Store | All (Fallback) | Uses AES-256-CBC encryption to store tokens in the ~/.pubm/ directory when native keychains are unavailable. |
Sources: README.md:104-114, README.zh-cn.md:112-120, plugins/pubm-plugin/skills/publish-setup/SKILL.md:183-189
Token Resolution Flow
The system follows a strict priority order when resolving tokens for authentication. Environment variables always take precedence to support CI/CD workflows and manual overrides.
GitHub Authentication Handling
The system specifically manages GitHub Personal Access Tokens (PAT) for operations such as creating GitHub Releases and pushing tags.
Resolution Logic
The function resolveGitHubToken attempts to locate a token in the following order:
process.env.GITHUB_TOKEN- Secure storage (Native Keychain or Encrypted Fallback)
If found in secure storage, the token is temporarily assigned to process.env.GITHUB_TOKEN for use by the current session.
Sources: packages/core/src/utils/github-token.ts:10-23, packages/core/src/tasks/phases/push-release.ts:86-89
Interactive Acquisition
In non-CI (local) environments, if a token is not found, the system prompts the user via an interactive task. The user can choose to:
- Enter Token: Manually provide a PAT, which is then saved to secure storage via
saveGitHubToken. - Browser Fallback: Open a release draft in the browser if no token is available to create a release via API.
- Skip: Bypass release creation.
Sources: packages/core/src/tasks/phases/push-release.ts:91-119, packages/core/src/i18n/locales/en.json:151-155
Registry-Specific Token Usage
Different registries utilize specific tokens and environment variables during the publication phase.
| Registry | Environment Variable | Secure Store Support |
|---|---|---|
| npm | NODE_AUTH_TOKEN | Supported via OS Keychain |
| jsr | JSR_TOKEN | Supported; encrypted local store enabled by default |
| crates.io | CARGO_REGISTRY_TOKEN | Supported via cargo login or OS Keychain |
Sources: plugins/pubm-plugin/skills/publish-setup/SKILL.md:183-189, packages/core/src/i18n/locales/en.json:204-220
Security Configuration
Users can control how tokens are persisted through CLI flags or configuration files:
--no-save-token: Prevents tokens (particularly JSR) from being saved to the encrypted local store, forcing a prompt each time.saveToken: boolean: A configuration field inpubm.config.tsto toggle local storage persistence.
Sources: README.md:107-108, plugins/pubm-plugin/skills/publish-setup/references/config-examples.md:139
CI/CD Integration
In CI environments, pubm operates in a headless mode where secure local storage is typically unavailable or not persistent. It relies entirely on repository secrets mapped to environment variables.
The preparation phase (--phase prepare) validates the availability and permissions of tokens found in the environment before any changes are made to the project or repository.
Sources: README.md:65-68, packages/core/src/i18n/locales/en.json:71-78
Summary
pubm implements a secure credential management system that balances developer convenience with enterprise-grade security. By leveraging native OS keychains and AES-256-CBC encryption for local persistence, it minimizes the risk of token leakage while maintaining a seamless workflow across npm, jsr, and crates.io. In CI/CD contexts, the system transitions gracefully to environment-based authentication, ensuring security through repository secrets.