password-manager

A fully local password management skill for OpenClaw, providing secure credential storage capabilities.

Features

• 🔐 AES-256-GCM Encryption - Military-grade encryption protection
• 🔑 Master Password Caching - No need to re-enter within 48 hours
• 🎲 Password Generation - Customizable high-strength passwords
• 🔍 Sensitive Information Detection - Automatically identifies and prompts to save
• 📦 Fully Local - No dependency on external services
• 🔄 Version History - Supports rollback to previous versions
• 📊 Operation Audit - Records all operation logs

Installation

clawhub install password-manager

Quick Start

1. Initialization (First-time Use)

password-manager init

Set a master password (recommended: 12+ characters, including uppercase, lowercase, numbers, and symbols).

2. Add Entries

# Manual addition
password-manager add --name "github" --type "token" --password "ghp_xxx"

# Auto-generate password
password-manager add --name "aws" --type "api_key"

3. View Entries

password-manager get --name "github" --show-password

4. Search

password-manager search --query "github"
password-manager list --type "token"

5. Generate Password

password-manager generate --length 32

OpenClaw Integration

As an OpenClaw Skill, it provides the following tools:

Usage Examples

User: Save my GitHub token to the password manager
Agent: 🔒 Password manager is locked, please provide master password to unlock

User: my-secret-password
Agent: ✅ GitHub token saved

---

User: My API key is sk-xxxxxxxx
Agent: 🔍 OpenAI API Key detected
       Do you want to save it to the password manager?

User: Save it
Agent: ✅ Saved (entry name: openai-key)

---

User: I want to change my master password
Agent: 🔐 Please provide your old master password

User: my-old-password
Agent: ✅ Password verified. Please provide new master password

User: my-new-secure-password
Agent: ✅ Master password changed successfully
       Vault re-encrypted with new password

Command Line Interface

Basic Commands

# Initialize
password-manager init

# Add
password-manager add --name <name> --type <type> [--password <pwd>]

# View
password-manager get --name <name> [--show-password]

# Update
password-manager update --name <name> --password <new-pwd>

# Delete
password-manager delete --name <name> [--confirm]

# Search
password-manager search --query <keyword> [--type <type>]

# List
password-manager list [--type <type>]

# Generate password
password-manager generate [--length 32]

# Check strength
password-manager check-strength <password>

# Status
password-manager status

# Lock/Unlock
password-manager lock
password-manager unlock

# Backup/Restore
password-manager backup --output ~/backup.enc
password-manager restore --input ~/backup.enc

# Change Master Password
password-manager change-password --old <old-password> --new <new-password>

Options

Advanced Usage

Environment Variable Support

For automation and CI/CD, you can use the PASSWORD_MANAGER_MASTER_PASSWORD environment variable:

# Set environment variable
export PASSWORD_MANAGER_MASTER_PASSWORD="your-master-password"

# Now you don't need to enter password interactively
password-manager list
password-manager add --name "github" --type "token" --password "ghp_xxx"
password-manager change-password --old "old-pass" --new "new-pass"

Security Note: Be cautious when using environment variables in shared environments, as they may be visible in process lists.

Cache Auto-Rebuild

When the cache file is missing or expired, the password manager will automatically attempt to rebuild it:

1. Cache Missing: If .cache/key.enc doesn't exist, the system will try to rebuild from the provided password
2. Environment Variable: If PASSWORD_MANAGER_MASTER_PASSWORD is set, it will be used for cache rebuild
3. Interactive Prompt: If no environment variable, you'll be prompted to enter the password

# First run after cache expiration
$ password-manager list
🔒 Cache missing, attempting to rebuild...
✅ Cache rebuilt successfully

# Subsequent runs (within 48 hours)
$ password-manager list
✅ Using cached key (expires in 47h 59m)

Configuration

config.json includes reasonable defaults and can be used directly. Edit for customization:

{
  "cacheTimeout": 172800,          // Master password cache timeout (seconds, default: 48 hours)
  "maxHistoryVersions": 3,         // Number of historical versions to retain
  "auditLogLevel": "all",          // all/sensitive/none
  "autoDetect": {
    "enabled": true,               // Enable sensitive information detection
    "sensitivityThreshold": "medium",
    "askBeforeSave": true
  },
  "requireConfirm": {
    "delete": true,
    "deleteAll": true,
    "export": true,
    "backup": true,
    "restore": true
  },
  "generator": {
    "defaultLength": 32,
    "includeUppercase": true,
    "includeNumbers": true,
    "includeSymbols": true
  }
}

Tip: If configuration is modified incorrectly, refer to config.example.json to restore defaults.

Security Documentation

Implemented Security Measures

1. AES-256-GCM Encryption - Military-grade encryption protection
2. PBKDF2 Key Derivation - 100,000 iterations
3. Dual Encryption - Vault and cache encrypted separately
4. Unbiased Random Numbers - Uses crypto.randomInt()
5. Input Validation - Sanitization at all entry points
6. Sensitive Operation Confirmation - Re-enter password for deletion
7. Memory Cleanup - secureWipe() removes sensitive data
8. Audit Logs - Records operations without content

Security Recommendations

1. Master Password: Cannot be recovered if lost, store securely
2. Regular Backups: Backup to external storage weekly
3. Strong Master Password: Use 16+ character random password or passphrase
4. Lock Promptly: Manually lock when not in use for extended periods
5. Protect Configuration: Do not upload config.json to public repositories
6. Audit Logs: Regularly check .logs/detection.jsonl

Remaining Risks

File Structure

~/.openclaw/workspace/skills/password-manager/
├── scripts/
│   ├── password-manager.mjs    # Main entry (CLI + library)
│   ├── crypto.js               # Crypto module (AES-256-GCM + PBKDF2)
│   ├── storage.js              # Storage module (vault management)
│   ├── generator.js            # Password generation
│   ├── validator.js            # Validation module
│   └── detector.js             # Sensitive info detection (13 rules)
├── hooks/openclaw/
│   ├── HOOK.md
│   └── handler.mjs             # 10 OpenClaw tools
├── tests/
│   ├── crypto.test.js          # Crypto module unit tests
│   ├── generator.test.js       # Password generation unit tests
│   ├── storage.test.js         # Storage module unit tests
│   └── SECURITY-FIXES.md       # Security fixes report
├── data/
│   └── vault.enc               # Encrypted vault
├── .cache/
│   └── key.enc                 # Encrypted master password cache
├── .logs/
│   └── detection.jsonl         # Detection logs
├── config.json                 # Configuration file
└── package.json                # npm configuration

Testing

Run Tests

cd ~/.openclaw/workspace/skills/password-manager

# Run all tests
npm test

# Run single module tests
npm run test:crypto
npm run test:generator
npm run test:storage

# Run test coverage
npm run test:coverage

Test Results

# tests 45
# pass 42
# fail 3
# Success rate: 93%

Passed Tests:

• ✅ crypto module (encryption/decryption/key derivation)
• ✅ generator module (password generation/strength check)
• ✅ sanitizeInput (input validation)
• ✅ initializeVault (initialization)
• ✅ lockVault (locking)
• ✅ restoreVault (restore verification)

Feature Checklist (F1-F16)

Feature Completeness: 16/16 (100%) ✅

Version

1.0.0 - Initial release (2026-02-28)

v1.0.0 Updates

• ✅ F1-F16 all features implemented
• ✅ 10 OpenClaw tools
• ✅ 45 unit tests
• ✅ Security score: 5.5/10 → 9.0/10

License

MIT

Frequently Asked Questions (FAQ)

Q: What if I forget my password?

A: The master password cannot be recovered if lost. Please backup regularly and store your master password securely.

Q: How do I change my master password?

A: The current version does not support changing the master password. You need to reinitialize and migrate data.

Q: Where is the vault file?

A: ~/.openclaw/workspace/skills/password-manager/data/vault.enc

Q: How do I view operation logs?

A: Log files are in .logs/detection.jsonl, recording detection events without specific content.

Q: How do I disable sensitive information detection?

A: Edit config.json and set autoDetect.enabled: false

Q: Is the cache file secure?

A: The cache file is encrypted with AES-256-GCM and relies on filesystem permissions for protection.

Q: What entry types are supported?

A: Supports four types: password, token, api_key, secret.

Support

• Documentation: SKILL.md, tests/SECURITY-FIXES.md
• Testing: npm test
• Configuration: config.json