AuthLock - MFA-bound Secret Protection (机密保护)

Provides TOTP-based encryption for sensitive data (passwords, certificates, keys), requiring MFA verification for each decryption.

Installation (安装)

# Install dependencies (安装依赖)
pip3 install --user cryptography pyotp qrcode

Usage:

# Direct call (recommended)
python3 \x3CSKILL_DIR>/authlock_cli.py \x3Ccommand>

# Or add temporary alias (current shell only)
alias authlock='python3 \x3CSKILL_DIR>/authlock_cli.py'

\x3CSKILL_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 (位置级别)

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

# 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

# Show current location and lookup paths
authlock which

# List all existing locations
authlock locations

Location-specific Operations

# 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 (初始化)

# 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) / 封印（加密）

# 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) / 解密

# 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

# 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:

# 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 授权隔离原则

每次解密都是独立事件，必须单独验证：

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-\x3CNAME> format in documents to reference encrypted secrets.

Reference Format

AUTHLOCK-\x3CUPPERNAME>

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 \x3CSKILL_DIR>/authlock_cli.py open \x3Cname> --code \x3Ccode>
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

# 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 path