PaddedCell

OpenClaw plugin for secure password management, safe command execution, and coordinated agent restart.

⚠️ Security Model

pcexec + pcguard mitigate light model hallucination / misoperation / prompt forgetting. They do not defend against malicious attacks. For stronger security, use sandbox mode instead of this plugin.

Features

1. pass_mgr — Password Manager (Go)

AES-256-GCM encryption with a build-time secret injected at compile time. Secrets are stored per-agent under pc-pass-store/<agent-id>/<key>.gpg.

Agent commands (require pcguard — must run through pcexec):

pass_mgr list                                     # List keys for current agent
pass_mgr get-secret --key <key>                    # Output secret
pass_mgr get-username --key <key>                  # Output username
pass_mgr set --key <key> --secret <s> [--username <u>]  # Set entry
pass_mgr generate --key <key> [--username <u>]     # Generate random secret
pass_mgr unset --key <key>                         # Delete entry
pass_mgr get <key>                                 # Legacy (maps to get-secret)

Admin commands (human-only — rejected if any AGENT_* env var is set):

pass_mgr admin handoff [file]       # Export build secret to file (default: pc-pass-store.secret)
pass_mgr admin init-from [file]     # Re-encrypt all data from old build secret to current

2. pcguard — Exec Guard (Go)

Validates that a process is running inside a pcexec context by checking environment sentinels (AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE). Returns exit code 1 if any check fails.

#!/bin/bash
pcguard || exit 1
# ... rest of script

3. pcexec — Safe Execution Tool (TypeScript)

Drop-in replacement for exec that:

Resolves $(pass_mgr get-secret --key <key>) and legacy $(pass_mgr get <key>) inline
Sanitizes all resolved passwords from stdout/stderr
Injects AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE environment variables
Appends $(openclaw path)/bin to PATH (making pcguard and pass_mgr available)

4. safe-restart — Coordinated Restart (TypeScript)

Agent state management and coordinated gateway restart.

Project Structure

PaddedCell/
├── plugin/              # Plugin source (TypeScript)
│   ├── commands/        #   Slash commands
│   ├── core/            #   Core modules (safe-restart, status, api)
│   ├── hooks/           #   Lifecycle hooks
│   ├── tools/           #   Tool definitions (pcexec)
│   ├── index.ts         #   Plugin entry point
│   ├── openclaw.plugin.json
│   ├── package.json
│   └── tsconfig.json
├── pass_mgr/            # Go password manager binary
│   └── src/main.go
├── pcguard/             # Go exec guard binary
│   └── src/main.go
├── dist/padded-cell/    # Build output
├── install.mjs          # Installer
└── README.md

Installation

# Install (default: ~/.openclaw)
node install.mjs

# Install with custom openclaw profile path
node install.mjs --openclaw-profile-path /path/to/.openclaw

# Build only (no install)
node install.mjs --build-only

# Uninstall
node install.mjs --uninstall

The installer automatically generates a random 32-byte build secret (stored in .build-secret, gitignored) and injects it into pass_mgr at compile time. Subsequent builds reuse the same secret.

Install paths

Priority: --openclaw-profile-path → $OPENCLAW_PATH → ~/.openclaw

Binaries → $(openclaw path)/bin/, plugin files → $(openclaw path)/plugins/padded-cell/.

Plugin Update Workflow (admin handoff)

When you rebuild PaddedCell (which generates a new build secret), existing encrypted data needs re-encryption:

# 1. Before updating — export current build secret
~/.openclaw/bin/pass_mgr admin handoff

# 2. Rebuild & reinstall (generates new .build-secret)
rm .build-secret
node install.mjs

# 3. After updating — re-encrypt data with new secret
~/.openclaw/bin/pass_mgr admin init-from

# 4. Restart gateway
openclaw gateway restart

Usage

# Agent sets and gets private passwords (via pcexec)
pass_mgr set --key myservice --secret s3cret --username admin
pass_mgr get-secret --key myservice
pass_mgr get-username --key myservice

# Shared scope (.public)
pass_mgr set --public --key shared-api --secret s3cret
pass_mgr list --public
pass_mgr get-secret --public --key shared-api

# Use in shell commands (pcexec resolves and sanitizes)
curl -u "$(pass_mgr get-username --key myservice):$(pass_mgr get-secret --key myservice)" https://api.example.com

License

MIT

4.7 KiB Raw Blame History