ClawHub

authlock

Security

AuthLock (机密保护) - MFA-bound secret protection. Triggers when user mentions authlock, secret protection (机密保护), TOTP encryption, MFA binding (MFA绑定), password vault (密码保险箱), certificate encryption (证书加密).

Install

openclaw skills install authlock

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

LevelLocationDescription
System (系统级)~/.authlock/Shared across all workspaces, default
Workspace (工作区级)<WORKSPACE>/.authlock/Independent for current workspace
User (用户级)Custom pathUser-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

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

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

禁止说明
❌ 复用 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 ExampleActual Secret NameDescription
AUTHLOCK-TEST-HELLOtest-helloTest secret
AUTHLOCK-DB-PASSWORDdb-passwordDatabase password
AUTHLOCK-PROD-SSH-KEYprod-ssh-keySSH 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

# 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
More in Security