147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
|
# hemmelig
|
||
|
|
|
||
|
|
CLI and library for creating encrypted, self-destructing secrets via [Hemmelig](https://hemmelig.app).
|
||
|
|
|
||
|
|
```
|
||
|
|
_ _ _ _
|
||
|
|
| | | | ___ _ __ ___ _ __ ___ ___| (_) __ _
|
||
|
|
| |_| |/ _ \ '_ ` _ \| '_ ` _ \ / _ \ | |/ _` |
|
||
|
|
| _ | __/ | | | | | | | | | | __/ | | (_| |
|
||
|
|
|_| |_|\___|_| |_| |_|_| |_| |_|\___|_|_|\__, |
|
||
|
|
|___/
|
||
|
|
```
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **Client-side AES-256-GCM encryption** - Your secrets are encrypted before leaving your machine
|
||
|
|
- **Zero-knowledge** - The server never sees your plaintext secrets
|
||
|
|
- **Self-destructing** - Secrets auto-delete after views or expiration
|
||
|
|
- **Password protection** - Optional additional security layer
|
||
|
|
- **Works with any Hemmelig instance** - Use hemmelig.app or self-hosted
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install -g hemmelig
|
||
|
|
```
|
||
|
|
|
||
|
|
Or use with npx:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npx hemmelig "my secret"
|
||
|
|
```
|
||
|
|
|
||
|
|
## CLI Usage
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Create a simple secret
|
||
|
|
hemmelig "my secret message"
|
||
|
|
|
||
|
|
# With a title and custom expiration
|
||
|
|
hemmelig "API key: sk-1234" -t "Production API Key" -e 7d
|
||
|
|
|
||
|
|
# Password protected
|
||
|
|
hemmelig "sensitive data" -p "mypassword"
|
||
|
|
|
||
|
|
# Multiple views allowed
|
||
|
|
hemmelig "shared config" -v 5
|
||
|
|
|
||
|
|
# Pipe from stdin
|
||
|
|
cat config.json | hemmelig -t "Config file"
|
||
|
|
echo "my secret" | hemmelig
|
||
|
|
|
||
|
|
# Use a self-hosted instance
|
||
|
|
hemmelig "internal secret" -u https://secrets.company.com
|
||
|
|
```
|
||
|
|
|
||
|
|
### Options
|
||
|
|
|
||
|
|
| Option | Description |
|
||
|
|
| ----------------------- | ------------------------------------------------------ |
|
||
|
|
| `-t, --title <title>` | Set a title for the secret |
|
||
|
|
| `-p, --password <pass>` | Protect with a password |
|
||
|
|
| `-e, --expires <time>` | Expiration: 5m, 30m, 1h, 4h, 12h, 1d, 3d, 7d, 14d, 28d |
|
||
|
|
| `-v, --views <number>` | Max views (1-9999, default: 1) |
|
||
|
|
| `-b, --burnable` | Burn after first view (default) |
|
||
|
|
| `--no-burnable` | Don't burn until all views used |
|
||
|
|
| `-u, --url <url>` | Base URL (default: https://hemmelig.app) |
|
||
|
|
| `-h, --help` | Show help |
|
||
|
|
| `--version` | Show version |
|
||
|
|
|
||
|
|
## Library Usage
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
import { createSecret } from 'hemmelig';
|
||
|
|
|
||
|
|
const result = await createSecret({
|
||
|
|
secret: 'my secret message',
|
||
|
|
title: 'API Key',
|
||
|
|
expiresIn: '1h',
|
||
|
|
views: 1,
|
||
|
|
burnable: true,
|
||
|
|
baseUrl: 'https://hemmelig.app', // optional
|
||
|
|
});
|
||
|
|
|
||
|
|
console.log(result.url); // https://hemmelig.app/secret/abc123#decryptionKey=...
|
||
|
|
console.log(result.id); // abc123
|
||
|
|
```
|
||
|
|
|
||
|
|
### API
|
||
|
|
|
||
|
|
#### `createSecret(options: SecretOptions): Promise<CreateSecretResult>`
|
||
|
|
|
||
|
|
Creates an encrypted secret on a Hemmelig server.
|
||
|
|
|
||
|
|
**Options:**
|
||
|
|
|
||
|
|
| Property | Type | Default | Description |
|
||
|
|
| ----------- | --------------- | ------------------------ | ----------------------------- |
|
||
|
|
| `secret` | `string` | required | The secret content to encrypt |
|
||
|
|
| `title` | `string` | - | Optional title |
|
||
|
|
| `password` | `string` | - | Password protection |
|
||
|
|
| `expiresIn` | `ExpirationKey` | `'1d'` | Expiration time |
|
||
|
|
| `views` | `number` | `1` | Max views (1-9999) |
|
||
|
|
| `burnable` | `boolean` | `true` | Burn on first view |
|
||
|
|
| `baseUrl` | `string` | `'https://hemmelig.app'` | Server URL |
|
||
|
|
|
||
|
|
**Returns:**
|
||
|
|
|
||
|
|
| Property | Type | Description |
|
||
|
|
| ----------- | -------- | ----------------------------- |
|
||
|
|
| `url` | `string` | Full URL to access the secret |
|
||
|
|
| `id` | `string` | The secret ID |
|
||
|
|
| `expiresIn` | `string` | The expiration time set |
|
||
|
|
|
||
|
|
## CI/CD Integration
|
||
|
|
|
||
|
|
### GitHub Actions
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
- name: Share deployment credentials
|
||
|
|
run: |
|
||
|
|
SECRET_URL=$(npx hemmelig "${{ secrets.DEPLOY_KEY }}" \
|
||
|
|
-t "Deployment Key" \
|
||
|
|
-e 1h)
|
||
|
|
echo "Secret URL: $SECRET_URL"
|
||
|
|
```
|
||
|
|
|
||
|
|
### GitLab CI
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
share-secret:
|
||
|
|
script:
|
||
|
|
- SECRET_URL=$(npx hemmelig "$DB_PASSWORD" -e 4h)
|
||
|
|
- echo "Secret URL: $SECRET_URL"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Security
|
||
|
|
|
||
|
|
- All encryption happens locally using AES-256-GCM
|
||
|
|
- Keys are derived using PBKDF2 with 600,000 iterations
|
||
|
|
- The decryption key is in the URL fragment (`#decryptionKey=...`), which is never sent to the server
|
||
|
|
- The server only stores encrypted data
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
MIT
|