AuthLock (机密保护) - MFA-bound secret protection. Triggers when user mentions authlock, secret protection (机密保护), TOTP encryption, MFA binding (MFA绑定), password...
---
name: authlock
description: AuthLock (机密保护) - MFA-bound secret protection. Triggers when user mentions authlock, secret protection (机密保护), TOTP encryption, MFA binding (MFA绑定), password vault (密码保险箱), certificate encryption (证书加密).
---
# AuthLock - MFA-bound Secret Protection (机密保护)
Provides TOTP-based encryption for sensitive data (passwords, certificates, keys), requiring MFA verification for each decryption.
## Installation (安装)
```bash
# Install dependencies (安装依赖)
pip3 install --user cryptography pyotp qrcode
```
**Usage**:
```bash
# Direct call (recommended)
python3 <SKILL_DIR>/authlock_cli.py <command>
# Or add temporary alias (current shell only)
alias authlock='python3 <SKILL_DIR>/authlock_cli.py'
```
> `<SKILL_DIR>` is the skill installation directory, the parent folder of this SKILL.md file.
## Multi-tenant Support (多租户支持)
Achieve tenant isolation via different locations, internal structure remains unchanged.
### Location Levels (位置级别)
| Level | Location | Description |
|-------|----------|-------------|
| System (系统级) | `~/.authlock/` | Shared across all workspaces, default |
| Workspace (工作区级) | `<WORKSPACE>/.authlock/` | Independent for current workspace |
| User (用户级) | Custom path | User-specified location |
### Lookup Priority
```
User (--path/AUTHLOCK_HOME) → Workspace → System
```
- **User level highest**: Via `--path` parameter or `AUTHLOCK_HOME` env var
- **Workspace level medium**: Auto-detect `OPENCLAW_WORKSPACE` env or current directory
- **System level fallback**: Default `~/.authlock/`
### Initialize Level
```bash
# Interactive selection (recommended)
authlock init
# Specify level
authlock init --level system # System level
authlock init --level workspace # Workspace level
authlock init --level user --path /custom/path # User level
```
### View Location
```bash
# Show current location and lookup paths
authlock which
# List all existing locations
authlock locations
```
### Location-specific Operations
```bash
# All commands support --path parameter
authlock seal secret.txt --name my-pass --path /custom/path
authlock open my-pass --code 123456 --path /custom/path
authlock list --path /custom/path
```
## Quick Start (快速开始)
### Initialize (初始化)
```bash
# Interactive level selection
authlock init
# Or specify level
authlock init --level system
authlock init --level workspace
authlock init --level user --path /custom/path
# Or import existing seed
authlock init --seed JBSWY3DPEHPK3PXP
```
Initialization displays QR code, scan with Microsoft Authenticator.
### Seal (Encrypt) / 封印(加密)
```bash
# Encrypt file
authlock seal ~/.ssh/id_rsa --name my-server-key
# Encrypt text (from pipe)
echo "super_secret_password" | authlock seal - --name db-password
# Encrypt with specified name
authlock seal ~/.ssh/server.pem --name prod-ssh-key
```
### Open (Decrypt) / 解密
```bash
# Decrypt to stdout
authlock open my-server-key --code 123456
# Decrypt to file
authlock open my-server-key --code 123456 --output ~/.ssh/id_rsa
# Decrypt and execute (SSH example)
authlock open prod-ssh-key --code 123456 --exec "ssh -i - user@host"
```
### Management
```bash
# List all sealed secrets
authlock list
# Delete secret
authlock delete old-password
# Show current location
authlock which
# List all locations
authlock locations
```
## How It Works
```
┌─────────────────────────────────────────────────────────┐
│ Encryption Flow │
│ │
│ Sensitive data ──┐ │
│ ├──► AES-256-GCM ──► Ciphertext │
│ TOTP seed ───────┘ │
│ + salt │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ Decryption Flow │
│ │
│ User enters TOTP code (123456) │
│ │ │
│ ▼ │
│ Code valid ✓ ──► Derive key ──► AES-256-GCM decrypt │
│ ──► Plaintext │
│ │
└─────────────────────────────────────────────────────────┘
```
## Configuration
### Optional PIN
Add second layer protection:
```bash
# Set PIN
authlock config --set-pin
# Enable mandatory PIN
authlock config --require-pin
# Now each decryption needs TOTP + PIN
authlock open my-key --code 123456 --pin
```
## Security Notes (安全说明)
### ⚠️ TOTP 授权隔离原则
**每次解密都是独立事件,必须单独验证:**
| 禁止 | 说明 |
|------|------|
| ❌ 复用 TOTP code | "刚才已经提供过 code 了" |
| ❌ 缓存 code | 将 code 存储起来后续使用 |
| ❌ 批量授权 | 一次 code 覆盖多次解密 |
| 必须 | 说明 |
|------|------|
| ✅ 每次独立询问 | 每次 `open` 都询问当前有效的 TOTP |
| ✅ 验证时效性 | TOTP 有效期约 30 秒,过期必须重新获取 |
| ✅ 即用即弃 | 解密后明文仅用于当前操作,不保留 |
**Agent 执行流程:**
```
用户请求解密 AUTHLOCK-xxx
↓
询问:"请提供当前有效的 TOTP code"
↓
用户提供 code (如: 123456)
↓
执行: authlock open xxx --code 123456
↓
使用明文执行操作 (SSH连接等)
↓
清除内存中的明文
```
**重要:** 即使对话中有过解密操作,下次请求时必须重新询问 TOTP code。
---
### ⛔ Absolute Prohibitions (绝对禁止事项)
**Never echo plaintext password in conversation! (绝对不能在会话中回显明文密码!)**
- Agent must **never** show decrypted plaintext in chat response
- Even with `--output` to file, don't echo file contents
- Plaintext input during `seal` operation also shouldn't be echoed
- To confirm success, only return "✅ Sealed/Decrypted", not content
**Example (wrong vs correct)**:
```
❌ Wrong: Decryption successful, password: super_secret_password
✅ Correct: ✅ Decrypted to specified file
```
### Session Security
- Decrypted result only for **in-memory operations** (SSH connection, DB connection)
- **Not written to chat history**
- **Not written to session cache files**
- Immediately clear plaintext from memory after operation
### Other Security Notes
1. **TOTP seed safety**: Seed stored in config file, backup carefully
2. **Time sync**: Ensure accurate system time, TOTP depends on time
3. **Memory safety**: Decrypted plaintext exists briefly in memory only
4. **Backup**: Backup corresponding `~/.authlock/` directory
## Trigger Keywords
authlock, secret protection, TOTP encryption, MFA binding, password vault, certificate encryption
## Secret Reference Convention
Use `AUTHLOCK-<NAME>` format in documents to reference encrypted secrets.
### Reference Format
```
AUTHLOCK-<UPPERNAME>
```
| Reference Example | Actual Secret Name | Description |
|-------------------|--------------------|-------------|
| `AUTHLOCK-TEST-HELLO` | `test-hello` | Test secret |
| `AUTHLOCK-DB-PASSWORD` | `db-password` | Database password |
| `AUTHLOCK-PROD-SSH-KEY` | `prod-ssh-key` | SSH private key |
**Naming rules**:
- Reference uses **uppercase letters** and **hyphens**
- Actual secret name: remove `AUTHLOCK-` prefix, convert to **lowercase**
- Example: `AUTHLOCK-DB-PASSWORD` → `db-password`
### Agent Usage Flow
1. **Discover reference**: Find `AUTHLOCK-xxx` format in document
2. **Request verification**: Ask user for current TOTP code
3. **Decrypt secret**: `python3 <SKILL_DIR>/authlock_cli.py open <name> --code <code>`
4. **In-memory use**: Keep decryption result in memory, **no disk write**
5. **Write file**: Only when user explicitly specifies output path
### Using in Documents
```markdown
# Server Configuration
- SSH Key: AUTHLOCK-PROD-SSH-KEY
- Database Password: AUTHLOCK-DB-PASSWORD
- API Token: AUTHLOCK-API-TOKEN
```
**Security principles**:
- Decrypted result should not be written to disk
- Agent should handle secret in memory only
- Only write to file when user explicitly specifies output pathdon't have the plugin yet? install it then click "run inline in claude" again.