# 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