bun-types 1.2.21-canary.20250822T140708 → 1.2.21-canary.20250824T140615

package/bun.d.ts

@@ -1844,6 +1844,10 @@ declare module "bun" {
       hideConsole?: boolean;
       icon?: string;
       title?: string;
+      publisher?: string;
+      version?: string;
+      description?: string;
+      copyright?: string;
     };
   }
 
@@ -2120,6 +2124,287 @@ declare module "bun" {
     ): string;
   };
 
+  /**
+   * Securely store and retrieve sensitive credentials using the operating system's native credential storage.
+   *
+   * Uses platform-specific secure storage:
+   * - **macOS**: Keychain Services
+   * - **Linux**: libsecret (GNOME Keyring, KWallet, etc.)
+   * - **Windows**: Windows Credential Manager
+   *
+   * @category Security
+   *
+   * @example
+   * ```ts
+   * import { secrets } from "bun";
+   *
+   * // Store a credential
+   * await secrets.set({
+   *   service: "my-cli-tool",
+   *   name: "github-token",
+   *   value: "ghp_xxxxxxxxxxxxxxxxxxxx"
+   * });
+   *
+   * // Retrieve a credential
+   * const token = await secrets.get({
+   *   service: "my-cli-tool",
+   *   name: "github-token"
+   * });
+   *
+   * if (token) {
+   *   console.log("Token found:", token);
+   * } else {
+   *   console.log("Token not found");
+   * }
+   *
+   * // Delete a credential
+   * const deleted = await secrets.delete({
+   *   service: "my-cli-tool",
+   *   name: "github-token"
+   * });
+   * console.log("Deleted:", deleted); // true if deleted, false if not found
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Replace plaintext config files
+   * import { secrets } from "bun";
+   *
+   * // Instead of storing in ~/.npmrc
+   * await secrets.set({
+   *   service: "npm-registry",
+   *   name: "https://registry.npmjs.org",
+   *   value: "npm_xxxxxxxxxxxxxxxxxxxx"
+   * });
+   *
+   * // Instead of storing in ~/.aws/credentials
+   * await secrets.set({
+   *   service: "aws-cli",
+   *   name: "default",
+   *   value: process.env.AWS_SECRET_ACCESS_KEY
+   * });
+   *
+   * // Load at runtime with fallback
+   * const apiKey = await secrets.get({
+   *   service: "my-app",
+   *   name: "api-key"
+   * }) || process.env.API_KEY;
+   * ```
+   */
+  const secrets: {
+    /**
+     * Retrieve a stored credential from the operating system's secure storage.
+     *
+     * @param options - The service and name identifying the credential
+     * @returns The stored credential value, or null if not found
+     *
+     * @example
+     * ```ts
+     * const password = await Bun.secrets.get({
+     *   service: "my-database",
+     *   name: "admin"
+     * });
+     *
+     * if (password) {
+     *   await connectToDatabase(password);
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Check multiple possible locations
+     * const token =
+     *   await Bun.secrets.get({ service: "github", name: "token" }) ||
+     *   await Bun.secrets.get({ service: "gh-cli", name: "github.com" }) ||
+     *   process.env.GITHUB_TOKEN;
+     * ```
+     */
+    get(options: {
+      /**
+       * The service or application name.
+       *
+       * Use a unique identifier for your application to avoid conflicts.
+       * Consider using reverse domain notation for production apps (e.g., "com.example.myapp").
+       */
+      service: string;
+
+      /**
+       * The account name, username, or resource identifier.
+       *
+       * This identifies the specific credential within the service.
+       * Common patterns include usernames, email addresses, or resource URLs.
+       */
+      name: string;
+    }): Promise<string | null>;
+
+    /**
+     * Store or update a credential in the operating system's secure storage.
+     *
+     * If a credential already exists for the given service/name combination, it will be replaced.
+     * The credential is encrypted by the operating system and only accessible to the current user.
+     *
+     * @param options - The service and name identifying the credential
+     * @param value - The secret value to store (e.g., password, API key, token)
+     *
+     * @example
+     * ```ts
+     * // Store an API key
+     * await Bun.secrets.set({
+     *   service: "openai-api",
+     *   name: "production",
+     *   value: "sk-proj-xxxxxxxxxxxxxxxxxxxx"
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Update an existing credential
+     * const newPassword = generateSecurePassword();
+     * await Bun.secrets.set({
+     *   service: "email-server",
+     *   name: "admin@example.com",
+     *   value: newPassword
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Store credentials from environment variables
+     * if (process.env.DATABASE_PASSWORD) {
+     *   await Bun.secrets.set({
+     *     service: "postgres",
+     *     name: "production",
+     *     value: process.env.DATABASE_PASSWORD
+     *   });
+     *   delete process.env.DATABASE_PASSWORD; // Remove from memory
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Delete a credential using empty string (equivalent to delete())
+     * await Bun.secrets.set({
+     *   service: "my-service",
+     *   name: "api-key",
+     *   value: "" // Empty string deletes the credential
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Store credential with unrestricted access for CI environments
+     * await Bun.secrets.set({
+     *   service: "github-actions",
+     *   name: "deploy-token",
+     *   value: process.env.DEPLOY_TOKEN,
+     *   allowUnrestrictedAccess: true // Allows access without user interaction on macOS
+     * });
+     * ```
+     */
+    set(options: {
+      /**
+       * The service or application name.
+       *
+       * Use a unique identifier for your application to avoid conflicts.
+       * Consider using reverse domain notation for production apps (e.g., "com.example.myapp").
+       */
+      service: string;
+
+      /**
+       * The account name, username, or resource identifier.
+       *
+       * This identifies the specific credential within the service.
+       * Common patterns include usernames, email addresses, or resource URLs.
+       */
+      name: string;
+
+      /**
+       * The secret value to store.
+       *
+       * This should be a sensitive credential like a password, API key, or token.
+       * The value is encrypted by the operating system before storage.
+       *
+       * Note: To delete a credential, use the delete() method or pass an empty string.
+       * An empty string value will delete the credential if it exists.
+       */
+      value: string;
+
+      /**
+       * Allow unrestricted access to stored credentials on macOS.
+       *
+       * When true, allows all applications to access this keychain item without user interaction.
+       * This is useful for CI environments but reduces security.
+       *
+       * @default false
+       * @platform macOS - Only affects macOS keychain behavior. Ignored on other platforms.
+       */
+      allowUnrestrictedAccess?: boolean;
+    }): Promise<void>;
+
+    /**
+     * Delete a stored credential from the operating system's secure storage.
+     *
+     * @param options - The service and name identifying the credential
+     * @returns true if a credential was deleted, false if not found
+     *
+     * @example
+     * ```ts
+     * // Delete a single credential
+     * const deleted = await Bun.secrets.delete({
+     *   service: "my-app",
+     *   name: "api-key"
+     * });
+     *
+     * if (deleted) {
+     *   console.log("Credential removed successfully");
+     * } else {
+     *   console.log("Credential was not found");
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Clean up multiple credentials
+     * const services = ["github", "npm", "docker"];
+     * for (const service of services) {
+     *   await Bun.secrets.delete({
+     *     service,
+     *     name: "token"
+     *   });
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Clean up on uninstall
+     * if (process.argv.includes("--uninstall")) {
+     *   const deleted = await Bun.secrets.delete({
+     *     service: "my-cli-tool",
+     *     name: "config"
+     *   });
+     *   process.exit(deleted ? 0 : 1);
+     * }
+     * ```
+     */
+    delete(options: {
+      /**
+       * The service or application name.
+       *
+       * Use a unique identifier for your application to avoid conflicts.
+       * Consider using reverse domain notation for production apps (e.g., "com.example.myapp").
+       */
+      service: string;
+
+      /**
+       * The account name, username, or resource identifier.
+       *
+       * This identifies the specific credential within the service.
+       * Common patterns include usernames, email addresses, or resource URLs.
+       */
+      name: string;
+    }): Promise<boolean>;
+  };
+
   /**
    * A build artifact represents a file that was generated by the bundler @see {@link Bun.build}
    *

package/docs/api/fetch.md

@@ -336,7 +336,7 @@ This will print the request and response headers to your terminal:
 ```sh
 [fetch] > HTTP/1.1 GET http://example.com/
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.21-canary.20250822T140708
+[fetch] > User-Agent: Bun/1.2.21-canary.20250824T140615
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/secrets.md

@@ -0,0 +1,319 @@
+Store and retrieve sensitive credentials securely using the operating system's native credential storage APIs.
+
+**Experimental:** This API is new and experimental. It may change in the future.
+
+```typescript
+import { secrets } from "bun";
+
+const githubToken = await secrets.get({
+  service: "my-cli-tool",
+  name: "github-token",
+});
+
+if (!githubToken) {
+  const response = await fetch("https://api.github.com/name", {
+    headers: { "Authorization": `token ${githubToken}` },
+  });
+  console.log("Please enter your GitHub token");
+} else {
+  await secrets.set({
+    service: "my-cli-tool",
+    name: "github-token",
+    value: prompt("Please enter your GitHub token"),
+  });
+  console.log("GitHub token stored");
+}
+```
+
+## Overview
+
+`Bun.secrets` provides a cross-platform API for managing sensitive credentials that CLI tools and development applications typically store in plaintext files like `~/.npmrc`, `~/.aws/credentials`, or `.env` files. It uses:
+
+- **macOS**: Keychain Services
+- **Linux**: libsecret (GNOME Keyring, KWallet, etc.)
+- **Windows**: Windows Credential Manager
+
+All operations are asynchronous and non-blocking, running on Bun's threadpool.
+
+Note: in the future, we may add an additional `provider` option to make this better for production deployment secrets, but today this API is mostly useful for local development tools.
+
+## API
+
+### `Bun.secrets.get(options)`
+
+Retrieve a stored credential.
+
+```typescript
+import { secrets } from "bun";
+
+const password = await Bun.secrets.get({
+  service: "my-app",
+  name: "alice@example.com",
+});
+// Returns: string | null
+
+// Or if you prefer without an object
+const password = await Bun.secrets.get("my-app", "alice@example.com");
+```
+
+**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
+
+### `Bun.secrets.set(options, value)`
+
+Store or update a credential.
+
+```typescript
+import { secrets } from "bun";
+
+await secrets.set({
+  service: "my-app",
+  name: "alice@example.com",
+  value: "super-secret-password",
+});
+```
+
+**Parameters:**
+
+- `options.service` (string, required) - The service or application name
+- `options.name` (string, required) - The username or account identifier
+- `value` (string, required) - The password or secret to store
+
+**Notes:**
+
+- If a credential already exists for the given service/name combination, it will be replaced
+- The stored value is encrypted by the operating system
+
+### `Bun.secrets.delete(options)`
+
+Delete a stored credential.
+
+```typescript
+const deleted = await Bun.secrets.delete({
+  service: "my-app",
+  name: "alice@example.com",
+  value: "super-secret-password",
+});
+// Returns: boolean
+```
+
+**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
+
+## Examples
+
+### Storing CLI Tool Credentials
+
+```javascript
+// Store GitHub CLI token (instead of ~/.config/gh/hosts.yml)
+await Bun.secrets.set({
+  service: "my-app.com",
+  name: "github-token",
+  value: "ghp_xxxxxxxxxxxxxxxxxxxx",
+});
+
+// Or if you prefer without an object
+await Bun.secrets.set("my-app.com", "github-token", "ghp_xxxxxxxxxxxxxxxxxxxx");
+
+// Store npm registry token (instead of ~/.npmrc)
+await Bun.secrets.set({
+  service: "npm-registry",
+  name: "https://registry.npmjs.org",
+  value: "npm_xxxxxxxxxxxxxxxxxxxx",
+});
+
+// Retrieve for API calls
+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}`,
+    },
+  });
+}
+```
+
+### Migrating from Plaintext Config Files
+
+```javascript
+// Instead of storing in ~/.aws/credentials
+await Bun.secrets.set({
+  service: "aws-cli",
+  name: "AWS_SECRET_ACCESS_KEY",
+  value: process.env.AWS_SECRET_ACCESS_KEY,
+});
+
+// Instead of .env files with sensitive data
+await Bun.secrets.set({
+  service: "my-app",
+  name: "api-key",
+  value: "sk_live_xxxxxxxxxxxxxxxxxxxx",
+});
+
+// Load at runtime
+const apiKey =
+  (await Bun.secrets.get({
+    service: "my-app",
+    name: "api-key",
+  })) || process.env.API_KEY; // Fallback for CI/production
+```
+
+### Error Handling
+
+```javascript
+try {
+  await Bun.secrets.set({
+    service: "my-app",
+    name: "alice",
+    value: "password123",
+  });
+} catch (error) {
+  console.error("Failed to store credential:", error.message);
+}
+
+// Check if a credential exists
+const password = await Bun.secrets.get({
+  service: "my-app",
+  name: "alice",
+});
+
+if (password === null) {
+  console.log("No credential found");
+}
+```
+
+### Updating Credentials
+
+```javascript
+// Initial password
+await Bun.secrets.set({
+  service: "email-server",
+  name: "admin@example.com",
+  value: "old-password",
+});
+
+// Update to new password
+await Bun.secrets.set({
+  service: "email-server",
+  name: "admin@example.com",
+  value: "new-password",
+});
+
+// The old password is replaced
+```
+
+## Platform Behavior
+
+### macOS (Keychain)
+
+- Credentials are stored in the name's login keychain
+- The keychain may prompt for access permission on first use
+- Credentials persist across system restarts
+- Accessible by the name who stored them
+
+### Linux (libsecret)
+
+- Requires a secret service daemon (GNOME Keyring, KWallet, etc.)
+- Credentials are stored in the default collection
+- May prompt for unlock if the keyring is locked
+- The secret service must be running
+
+### Windows (Credential Manager)
+
+- Credentials are stored in Windows Credential Manager
+- Visible in Control Panel → Credential Manager → Windows Credentials
+- Persist with `CRED_PERSIST_ENTERPRISE` flag so it's scoped per user
+- Encrypted using Windows Data Protection API
+
+## Security Considerations
+
+1. **Encryption**: Credentials are encrypted by the operating system's credential manager
+2. **Access Control**: Only the name who stored the credential can retrieve it
+3. **No Plain Text**: Passwords are never stored in plain text
+4. **Memory Safety**: Bun zeros out password memory after use
+5. **Process Isolation**: Credentials are isolated per name account
+
+## Limitations
+
+- Maximum password length varies by platform (typically 2048-4096 bytes)
+- Service and name names should be reasonable lengths (< 256 characters)
+- Some special characters may need escaping depending on the platform
+- Requires appropriate system services:
+  - Linux: Secret service daemon must be running
+  - macOS: Keychain Access must be available
+  - Windows: Credential Manager service must be enabled
+
+## Comparison with Environment Variables
+
+Unlike environment variables, `Bun.secrets`:
+
+- ✅ Encrypts credentials at rest (thanks to the operating system)
+- ✅ Avoids exposing secrets in process memory dumps (memory is zeroed after its no longer needed)
+- ✅ Survives application restarts
+- ✅ Can be updated without restarting the application
+- ✅ Provides name-level access control
+- ❌ Requires OS credential service
+- ❌ Not very useful for deployment secrets (use environment variables in production)
+
+## Best Practices
+
+1. **Use descriptive service names**: Match the tool or application name
+   If you're building a CLI for external use, you probably should use a UTI (Uniform Type Identifier) for the service name.
+
+   ```javascript
+   // Good - matches the actual tool
+   { service: "com.docker.hub", name: "username" }
+   { service: "com.vercel.cli", name: "team-name" }
+
+   // Avoid - too generic
+   { service: "api", name: "key" }
+   ```
+
+2. **Credentials-only**: Don't store application configuration in this API
+   This API is slow, you probably still need to use a config file for some things.
+
+3. **Use for local development tools**:
+   - ✅ CLI tools (gh, npm, docker, kubectl)
+   - ✅ Local development servers
+   - ✅ Personal API keys for testing
+   - ❌ Production servers (use proper secret management)
+
+## TypeScript
+
+```typescript
+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;
+}
+```
+
+## See Also
+
+- [Environment Variables](./env.md) - For deployment configuration
+- [Bun.password](./password.md) - For password hashing and verification

package/docs/api/spawn.md

@@ -140,7 +140,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
 ```ts
 const proc = Bun.spawn(["bun", "--version"]);
 const text = await proc.stdout.text();
-console.log(text); // => "1.2.21-canary.20250822T140708\n"
+console.log(text); // => "1.2.21-canary.20250824T140615\n"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`: