📦 authlock — 机密保护

提供基于 TOTP 的敏感数据（密码、证书、密钥）加密，每次解密都需要 MFA 验证。

Installation (安装)

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

Usage:

# Direct call (recommended)
python3 /authlock_cli.py 
# Or add temporary alias (current shell only)
alias authlock='python3 /authlock_cli.py'

is the skill installation directory, the parent folder of this SKILL.md file.

Multi-tenant Support (多租户支持)

通过不同位置实现租户隔离，内部结构保持不变。

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

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

用户请求解密 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

• TOTP seed safety: Seed stored in config file, backup carefully
• Time sync: Ensure accurate system time, TOTP depends on time
• Memory safety: Decrypted plaintext exists briefly in memory only
• Backup: Backup corresponding ~/.authlock/ directory

Trigger Keywords

authlock, secret protection, TOTP encryption, MFA binding, password vault, certificate encryption

Secret Reference Convention

Use AUTHLOCK- format in documents to reference encrypted secrets.

Reference Format

AUTHLOCK-

• Reference uses uppercase letters and hyphens
• Actual secret name: remove AUTHLOCK- prefix, convert to lowercase
• Example: AUTHLOCK-DB-PASSWORD → db-password

Agent Usage Flow

• Discover reference: Find AUTHLOCK-xxx format in document
• Request verification: Ask user for current TOTP code
• Decrypt secret: python3 /authlock_cli.py open --code
• In-memory use: Keep decryption result in memory, no disk write
• 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