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 /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 (多租户支持)

Achieve tenant isolation via different locations, internal structure remains unchanged.

Location Levels (位置级别)

| Level | Location | Description | |-------|----------|-------------| | System (系统级) | ~/.authlock/ | Shared across all workspaces, default | | Workspace (工作区级) | /.authlock/ | Independent for current workspace | | User (用户级) | Custom path | User-specified location |

Lookup Priority

User (--path/AUTHLOCK_HOME) → Workspace → System

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! (绝对不能在会话中回显明文密码！)

Example (wrong vs correct):

❌ Wrong: Decryption successful, password: super_secret_password
✅ Correct: ✅ Decrypted to specified file

Session Security

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

Reference Format

AUTHLOCK-

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

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 /authlock_cli.py open --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:

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