npm package: @redredchen01/secret-mgmt
Description: Secret management CLI — generate, rotate, store, fetch, audit, share, revoke
Author: redredchen01
Latest version: 1.0.0

# @redredchen01/secret-mgmt

> Secret management CLI — generate, rotate, store, fetch, audit, share, revoke

[![npm version](https://img.shields.io/npm/v/@redredchen01/secret-mgmt.svg)](https://www.npmjs.com/package/@redredchen01/secret-mgmt)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
npm install -g @redredchen01/secret-mgmt
```

## Quick Start

```bash
# Generate a random password
secret-mgmt generate

# Store a secret (prompts for encryption password)
secret-mgmt store --name db-pass --value "s3cr3t"

# Retrieve it
secret-mgmt fetch --name db-pass

# Rotate it
secret-mgmt rotate --name db-pass

# Audit all secrets
secret-mgmt audit

# Share a secret with a colleague
secret-mgmt share --name api-key

# Revoke (delete) a secret
secret-mgmt revoke --name old-token
```

## Environment Variables

| Variable             | Purpose                                              |
|----------------------|------------------------------------------------------|
| `FOUNDRY_SECRET_PASS`| Default encryption/decryption password (avoid shell history) |

## Commands

### `generate` — Generate random secret

Generate a cryptographically random secret using `openssl rand` (with `/dev/urandom` fallback).

```bash
secret-mgmt generate
secret-mgmt generate --type token --length 64
secret-mgmt generate --type uuid
secret-mgmt generate --type password --no-special --count 5
secret-mgmt generate --type hex --length 16 --json
```

Options: `--type TYPE`, `--length N`, `--no-special`, `--count N`, `--json`

Supported types: `password` (default), `token`, `uuid`, `hex`, `base64`

---

### `store` — Store encrypted secret

Encrypt and store a secret using AES-256-CBC with PBKDF2 key derivation.

```bash
secret-mgmt store --name db-pass --value "s3cr3t"
echo "s3cr3t" | secret-mgmt store --name db-pass
FOUNDRY_SECRET_PASS=mypass secret-mgmt store --name token --value "abc"
```

Options: `--name NAME`, `--value VALUE`, `--store DIR`, `--password PASS`, `--json`

Default store: `.secrets/` (created automatically, mode 700)

---

### `fetch` — Retrieve encrypted secret

Decrypt and print a stored secret to stdout.

```bash
secret-mgmt fetch --name db-pass
secret-mgmt fetch --name api-key --json
```

Options: `--name NAME`, `--store DIR`, `--password PASS`, `--json`

---

### `rotate` — Rotate a secret

Generate a new value for an existing secret. The old encrypted file is archived as `{name}.{timestamp}.enc`.

```bash
secret-mgmt rotate --name db-pass
secret-mgmt rotate --name api-key --type token --length 64
```

Options: `--name NAME`, `--store DIR`, `--type TYPE`, `--length N`, `--password PASS`, `--json`

---

### `audit` — Audit secret ages

Report all secrets in the store with their age in days. Flags EXPIRED (>= max-age) and STALE (>= max-age/2).

```bash
secret-mgmt audit
secret-mgmt audit --max-age 30 --json
```

Options: `--store DIR`, `--max-age DAYS` (default: 90), `--json`

---

### `share` — Share secret securely

Re-encrypt a stored secret with a separate password into a portable standalone file for sharing.

```bash
secret-mgmt share --name api-key
secret-mgmt share --name db-pass --output /tmp/db-pass.shared.enc --share-password "recipient-pass"
```

Recipient decrypts with:
```bash
openssl enc -d -aes-256-cbc -pbkdf2 -in {name}.shared.enc
```

Options: `--name NAME`, `--store DIR`, `--output FILE`, `--password PASS`, `--share-password P`, `--json`

---

### `revoke` — Revoke secret

Securely delete a secret. Uses `shred(1)` if available; falls back to random-data overwrite before `rm`.

```bash
secret-mgmt revoke --name old-api-key
secret-mgmt revoke --name db-pass --force
```

Options: `--name NAME`, `--store DIR`, `--force`, `--json`

---

## Security Notes

- Encryption: AES-256-CBC with `-pbkdf2` (falls back to `-md sha256` on older openssl)
- Passwords are never logged or echoed to stderr
- Password prompts read from `/dev/tty` to allow piped usage
- Store directory is created with mode 700; secret files with mode 600
- `revoke` uses `shred -u -z` when available for secure deletion

## JSON Output (Pipe Protocol)

All commands support `--json` for structured output compatible with the Skill Foundry pipe protocol:

```bash
secret-mgmt generate --type token --json | some-other-tool
secret-mgmt audit --json | jq '.data.expired'
```

## License

MIT