Password Manager

password-manager

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

Features

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:

| Tool | Function | Input Parameters | |------|----------|------------------| | password_manager_add | Add entry | name, type, username, password, tags, notes | | password_manager_get | Get entry | name, showPassword | | password_manager_update | Update entry | name, password, username, tags, notes | | password_manager_delete | Delete entry | name, confirmed | | password_manager_search | Search entries | query, type, tag | | password_manager_list | List entries | type | | password_manager_generate | Generate password | length, includeUppercase, includeNumbers, includeSymbols | | password_manager_check_strength | Check strength | password | | password_manager_status | View status | - | | password_manager_detect | Detect sensitive info | text | | password_manager_change_password | Change master password | oldPassword, newPassword |

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  --type  [--password ]
View
password-manager get --name  [--show-password]
Update
password-manager update --name  --password 
Delete
password-manager delete --name  [--confirm]
Search
password-manager search --query  [--type ]
List
password-manager list [--type ]
Generate password
password-manager generate [--length 32]
Check strength
password-manager check-strength 
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  --new 

Options

| Option | Description | |--------|-------------| | --name | Entry name (required) | | --type | Entry type (password/token/api_key/secret) | | --username | Username (optional) | | --password | Password/value (auto-generate if not provided) | | --tags | Tags (comma-separated, optional) | | --length | Password length (default: 32) | | --show-password | Show password in plaintext | | --confirm | Skip confirmation (for sensitive operations) | | --old | Old master password (for change-password) | | --new | New master password (for change-password) |

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

| Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Cache file depends on filesystem permissions | Low | Medium | Encrypted | | Memory keys may be dumped | Low | High | secureWipe added | | Master password loss cannot be recovered | - | High | User education |

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:

Feature Checklist (F1-F16)

| ID | Feature | Status | |----|---------|--------| | F1 | AES-256-GCM encrypted storage | ✅ | | F2 | CRUD operations | ✅ | | F3 | Password generation (customizable) | ✅ | | F4 | Password strength check | ✅ | | F5 | Master password 48-hour cache | ✅ | | F6 | Sensitive operation confirmation | ✅ | | F7 | Automatic sensitive info detection | ✅ | | F8 | Version history | ✅ | | F9 | Operation audit logs | ✅ | | F10 | OpenClaw tool integration | ✅ | | F11 | Tag system | ✅ | | F12 | Notes field | ✅ | | F13 | Search/filter | ✅ | | F14 | Backup/restore | ✅ | | F15 | Password strength recommendations | ✅ | | F16 | Auto-detection toggle | ✅ |

Feature Completeness: 16/16 (100%) ✅

Version

1.0.0 - Initial release (2026-02-28)

v1.0.0 Updates

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

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

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.