Bun.secrets overview and platform implementations
Bun.secrets provides a cross-platform API for managing sensitive credentials using operating system native credential storage. On macOS it uses Keychain Services, on Linux it uses libsecret (GNOME Keyring, KWallet, and other secret service daemons), and on Windows it uses Windows Credential Manager. All operations are asynchronous and non-blocking, running on Bun's threadpool. This API is mostly useful for local development tools, not production deployment secrets.
Bun.secrets.get() - retrieve stored credential
Bun.secrets.get(options) retrieves a stored credential. Parameters: options.service (string, required) - the service or application name; options.name (string, required) - the username or account identifier. Returns Promise<string | null> - the stored password, or null if not found. Can also be called without an object: Bun.secrets.get("my-app", "alice@example.com").
Bun.secrets.set() - store or update credential
Bun.secrets.set(options) stores or updates a credential. Parameters: options.service (string, required) - the service or application name; options.name (string, required) - the username or account identifier; options.value (string, required) - the password or secret to store. Returns Promise<void>. If a credential already exists for the given service/name combination, it is replaced. The stored value is encrypted by the operating system. Can also be called without an object: Bun.secrets.set("my-app", "github-token", "ghp_xxxx").
Bun.secrets.delete() - delete stored credential
Bun.secrets.delete(options) deletes a stored credential. Parameters: options.service (string, required) - the service or application name; options.name (string, required) - the username or account identifier. Returns Promise<boolean> - true if a credential was deleted, false if not found.
Bun.secrets basic example with GitHub token
This example demonstrates retrieving a GitHub token credential and using it to make an authenticated API call, with fallback to prompting for input if not found:
import { secrets } from "bun";
let githubToken: string | null = await secrets.get({
service: "my-cli-tool",
name: "github-token",
});
if (!githubToken) {
githubToken = prompt("Please enter your GitHub token");
await secrets.set({
service: "my-cli-tool",
name: "github-token",
value: githubToken,
});
console.log("GitHub token stored");
}
const response = await fetch("https://api.github.com/user", {
headers: { Authorization: `token ${githubToken}` },
});
console.log(`Logged in as ${(await response.json()).login}`);
Bun.secrets macOS behavior
On macOS, credentials are stored in the user's login keychain. The keychain may prompt for access permission on first use. Credentials persist across system restarts and are accessible only by the user who stored them.
Bun.secrets Linux behavior
On Linux, Bun.secrets requires a secret service daemon such as GNOME Keyring or KWallet to be running. Credentials are stored in the default collection and may prompt for unlock if the keyring is locked.
Bun.secrets Windows behavior
On Windows, credentials are stored in Windows Credential Manager, visible in Control Panel → Credential Manager → Windows Credentials. They are persisted with the CRED_PERSIST_ENTERPRISE flag, scoped per user, and encrypted using the Windows Data Protection API.
Bun.secrets security features
Bun.secrets provides the following security features: Credentials are encrypted by the operating system's credential manager. Only the user who stored the credential can retrieve it. Passwords are never stored in plain text. Bun zeros out password memory after use. Credentials are isolated per user account.
Bun.secrets limitations
Bun.secrets has the following limitations: Maximum password length varies by platform (typically 2048-4096 bytes). Keep service and name reasonably short (under 256 characters). Some special characters may need escaping depending on the platform. Requires appropriate system services - on Linux a secret service daemon must be running, on macOS Keychain Access must be available, and on Windows Credential Manager service must be enabled.
Bun.secrets advantages over environment variables
Unlike environment variables, Bun.secrets encrypts credentials at rest, avoids exposing secrets in process memory dumps by zeroing memory after use, survives application restarts, can be updated without restarting the application, and provides user-level access control. However, it requires OS credential service and is not useful for deployment secrets (use environment variables in production).
Bun.secrets best practices for service names
Use descriptive service names that match the tool or application name. For CLI tools meant for external use, use a Uniform Type Identifier (UTI) for the service name. Good examples: { service: "com.docker.hub", name: "username" } and { service: "com.vercel.cli", name: "team-name" }. Avoid generic names like { service: "api", name: "key" }.
Bun.secrets use cases - local development only
Bun.secrets is designed for local development tools and should be used for CLI tools (gh, npm, docker, kubectl), local development servers, and personal API keys for testing. It should not be used for production servers - use proper secret management in production instead.
Bun.secrets TypeScript interface definition
The TypeScript definition for Bun.secrets is:
namespace Bun {
interface SecretsOptions {
service: string;
name: string;
}
interface Secrets {
get(options: SecretsOptions): Promise<string | null>;
set(options: SecretsOptions & { value: string }): Promise<void>;
delete(options: SecretsOptions): Promise<boolean>;
}
const secrets: Secrets;
}
Bun.secrets storing CLI credentials example
Example of storing GitHub and npm CLI tokens using Bun.secrets:
await Bun.secrets.set({
service: "my-app.com",
name: "github-token",
value: "ghp_xxxxxxxxxxxxxxxxxxxx",
});
await Bun.secrets.set({
service: "npm-registry",
name: "https://registry.npmjs.org",
value: "npm_xxxxxxxxxxxxxxxxxxxx",
});
const token = await Bun.secrets.get({
service: "gh-cli",
name: "github.com",
});
if (token) {
const response = await fetch("https://api.github.com/name", {
headers: {
Authorization: `token ${token}`,
},
});
}
Bun.secrets error handling example
Example of error handling and checking for credential existence:
try {
await Bun.secrets.set({
service: "my-app",
name: "alice",
value: "password123",
});
} catch (error) {
console.error("Failed to store credential:", error.message);
}
const password = await Bun.secrets.get({
service: "my-app",
name: "alice",
});
if (password === null) {
console.log("No credential found");
}