@bytehide/secrets
Version:
The official ByteHide Secrets Manager SDK for Node.js/TypeScript, enabling secure retrieval and management of environment-based secrets, rotation, and auditing. Eliminate hardcoded credentials and keep your secrets out of code.
226 lines (158 loc) • 7.35 kB
Markdown
# ByteHide Secrets Manager for JavaScript/TypeScript ⚡
Automatically manage and retrieve secrets in your JavaScript/TypeScript projects—no more leaking `.env` files or hardcoded credentials! **ByteHide Secrets** is the official secrets manager SDK for Node.js/TS, seamlessly integrated with the ByteHide platform. It supports environment-based secrets, caching, optional in-memory encryption, and more.
[](https://www.npmjs.com/package/@bytehide/secrets)
[](https://www.npmjs.com/package/@bytehide/secrets)
[](https://github.com/ByteHide/bytehide-secrets/blob/main/LICENSE)
[**Official Documentation**](https://www.bytehide.com/docs/platforms/js/products/secrets)
> **Tip**: If you need to detect hardcoded secrets or scan your code for credentials, check out [**@bytehide/secrets-scanner**](https://www.npmjs.com/package/@bytehide/secrets-scanner), our free secrets scanner.
## Key Features
- **Easy Initialization**: Automatically detect your ByteHide token & environment from environment variables or manually initialize in code.
- **Enterprise security**: Enterprise encryption, privacy-first solution with RBAC and top-security integrations.
- **Environment-Aware**: Different secrets for dev, staging, and production—no separate `.env` for each environment.
- **Sync & Async APIs**: `get`, `set` with Promises, or `getSync`, `setSync` for synchronous usage.
- **Caching**: Time-to-live (TTL)–based in-memory cache, configurable and easily cleared.
- **Optional Encryption**: Store secrets in memory with a simple XOR-based fallback encryption.
- **One-Liner Setup**: No complex multi-stage config required.
## Installation
```bash
npm install @bytehide/secrets
# or
yarn add @bytehide/secrets
```
## 1. Obtain a Free Token
1. Create a free account at [cloud.bytehide.com/register](https://cloud.bytehide.com/register).
2. Set up a **Secrets** project and grab your **Project Token**.
3. Keep this token **private**—never commit it to Git.
## Environment Variables
You can store your **ByteHide** credentials in:
1. **Environment Variables** on your server (AWS, Railway, etc.).
2. A local `.env` file (for Node.js projects).
3. During your **build process** (for browser-based or serverless apps).
> **Required**:
> - `BYTEHIDE_SECRETS_TOKEN`
> - `BYTEHIDE_SECRETS_ENVIRONMENT` (if missing, default: _production_)
### Browser Projects (e.g., Vite or Webpack)
If you’re building for the browser, you need to inject environment variables at **build time**.
#### Webpack Example
```js
// webpack.config.js
const webpack = require('webpack');
module.exports = {
// ...
plugins: [
new webpack.DefinePlugin({
'window.env': JSON.stringify({
BYTEHIDE_SECRETS_ENVIRONMENT: 'production',
BYTEHIDE_SECRETS_TOKEN: 'your-project-token'
})
})
]
};
```
#### Vite Example
```js
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
define: {
'window.env': {
BYTEHIDE_SECRETS_ENVIRONMENT: 'production',
BYTEHIDE_SECRETS_TOKEN: 'your-project-token'
}
}
});
```
In your code, `SecretsManager` can read these values from `window.env` or an equivalent approach.
### Node.js Projects
1. Create a **`.env`** file in your project root:
```dotenv
BYTEHIDE_SECRETS_ENVIRONMENT=production
BYTEHIDE_SECRETS_TOKEN=your-project-token
```
2. Now `process.env.BYTEHIDE_SECRETS_TOKEN` and `process.env.BYTEHIDE_SECRETS_ENVIRONMENT` will be available to `SecretsManager`.
## Usage Examples
### Retrieving a Secret (Async)
```ts
import { SecretsManager } from "@bytehide/secrets";
async function main() {
// If environment variables are set, it auto-initializes
const apiKey = await SecretsManager.get("API_KEY");
console.log("API key:", apiKey);
}
main();
```
### Retrieving a Secret (Sync)
```ts
import { SecretsManager } from "@bytehide/secrets";
const pass = SecretsManager.getSync("DB_PASS");
console.log("Database password:", pass);
```
### Setting a Secret (Async)
```ts
await SecretsManager.set("NEW_SECRET", "myValue");
```
### Setting a Secret (Sync)
```ts
SecretsManager.setSync("ANOTHER_SECRET", "anotherValue");
```
### Example: Simulating a Database Connection
```ts
import { SecretsManager } from "@bytehide/secrets";
async function connectToDatabase() {
const dbUser = await SecretsManager.get("DB_USER");
const dbPass = await SecretsManager.get("DB_PASS");
// e.g., connect(dbUser, dbPass)
console.log("Connecting with", dbUser, dbPass);
}
connectToDatabase();
```
## API Overview
```ts
class SecretsManager {
static initialize(): void;
static unsecureInitialize(token: string, environment: string): void;
static configureCache(enabled: boolean, ttlMs?: number): void;
static clearCache(): void;
static get(key: string): Promise<string>;
static getSync(key: string): string;
static set(key: string, value: string): Promise<boolean>;
static setSync(key: string, value: string): boolean;
}
```
### Unsecure Initialization
```ts
SecretsManager.unsecureInitialize("my-token", "dev");
// Warns: do not use in production
```
If environment variables are **not** set, you can directly provide `token` and `environment`. This logs a warning about being unsecure—avoid in production.
### Caching
By default, caching is **enabled** with a 5-minute TTL. Configure as follows:
```ts
SecretsManager.configureCache(true, 10 * 60 * 1000); // 10 minutes
SecretsManager.clearCache();
```
## Additional Notes
- **Production Token**: Always store your production token in environment variables. Avoid committing tokens to Git.
## Why Choose ByteHide Secrets?
- **Official Integration** with the ByteHide platform: secrets scan, environment-based secrets, rotation, alerts and auditing all in one.
- **Node & Browser** support: adapt for serverless, front-end, or backend.
- **Minimal Setup**: No complicated config—just set two variables (`BYTEHIDE_SECRETS_TOKEN`, `BYTEHIDE_SECRETS_ENVIRONMENT`) or call `unsecureInitialize(...)`.
- **Scalable**: Works seamlessly in small Node scripts or large multi-environment deployments.
- **Multi-platform** support for JavaScript, Typescript, Dotnet (.NET) and more.
## Get Started Today
1. **Install**: `npm install @bytehide/secrets`
2. **Obtain a Token**: from [cloud.bytehide.com/register](https://cloud.bytehide.com/register).
3. **Set** environment variables or call `unsecureInitialize(...)`.
4. **Use** `SecretsManager.get(...)` or `SecretsManager.set(...)` to manage secrets.
**Need to detect secrets in your code?** Try [**@bytehide/secrets-scanner**](https://www.npmjs.com/package/@bytehide/secrets-scanner) for free scanning and automatic fixes.
For detailed documentation, check our [official docs](https://www.bytehide.com/docs/platforms/js/products/secrets) or contact [support@bytehide.com](mailto:support@bytehide.com). Good luck and stay secure!