zhi
98fc3da39c
M1: Rename pass_mgr to secret-mgr - Rename directory, binary, and Go module - Update install.mjs to build/install secret-mgr - Update pcexec.ts to support secret-mgr patterns (with legacy pass_mgr compat) - Update plugin config schema (passMgrPath → secretMgrPath) - Create new skills/secret-mgr/SKILL.md - install.mjs now initializes ego.json on install M2: Implement ego-mgr binary (Go) - Agent Scope and Public Scope column management - Commands: add column/public-column, delete, set, get, show, list columns - pcexec environment validation (AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE) - File locking for concurrent write safety - Proper exit codes per spec (0-6) - Agent auto-registration on read/write - Global column name uniqueness enforcement M3: ego-mgr Skill - Create skills/ego-mgr/SKILL.md with usage guide and examples Ref: REQUIREMENTS_EGO_MGR.md
179 lines
6.0 KiB
Markdown
179 lines
6.0 KiB
Markdown
<div align="center">
|
|
|
|
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
|
|
</div>
|
|
|
|
# PaddedCell
|
|
|
|
OpenClaw plugin for secure secret management, agent identity 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. secret-mgr — Secret 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):
|
|
|
|
```bash
|
|
secret-mgr list # List keys for current agent
|
|
secret-mgr get-secret --key <key> # Output secret
|
|
secret-mgr get-username --key <key> # Output username
|
|
secret-mgr set --key <key> --secret <s> [--username <u>] # Set entry
|
|
secret-mgr generate --key <key> [--username <u>] # Generate random secret
|
|
secret-mgr unset --key <key> # Delete entry
|
|
secret-mgr get <key> # Legacy (maps to get-secret)
|
|
```
|
|
|
|
**Admin commands** (human-only — rejected if any `AGENT_*` env var is set):
|
|
|
|
```bash
|
|
secret-mgr admin handoff [file] # Export build secret to file (default: pc-pass-store.secret)
|
|
secret-mgr admin init-from [file] # Re-encrypt all data from old build secret to current
|
|
```
|
|
|
|
### 2. ego-mgr — Agent Identity Manager (Go)
|
|
|
|
Manages agent personal information (name, email, timezone, etc.) stored in `~/.openclaw/ego.json`.
|
|
|
|
Supports **Agent Scope** (per-agent values) and **Public Scope** (shared by all agents).
|
|
|
|
**Commands** (require pcguard — must run through pcexec):
|
|
|
|
```bash
|
|
ego-mgr add column <name> [--default <val>] # Add agent-scope field
|
|
ego-mgr add public-column <name> [--default <val>] # Add public-scope field
|
|
ego-mgr delete <name> # Delete field and all values
|
|
ego-mgr set <name> <value> # Set field value
|
|
ego-mgr get <name> # Get field value
|
|
ego-mgr show # Show all fields and values
|
|
ego-mgr list columns # List all field names
|
|
```
|
|
|
|
### 3. 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.
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
pcguard || exit 1
|
|
# ... rest of script
|
|
```
|
|
|
|
### 4. pcexec — Safe Execution Tool (TypeScript)
|
|
|
|
Drop-in replacement for `exec` that:
|
|
- Resolves `$(secret-mgr get-secret --key <key>)` and legacy `$(pass_mgr get-secret --key <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`, `secret-mgr`, and `ego-mgr` available)
|
|
|
|
### 5. 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
|
|
├── secret-mgr/ # Go secret manager binary
|
|
│ └── src/main.go
|
|
├── ego-mgr/ # Go agent identity manager binary
|
|
│ └── src/main.go
|
|
├── pcguard/ # Go exec guard binary
|
|
│ └── src/main.go
|
|
├── skills/ # Agent skills
|
|
│ ├── secret-mgr/SKILL.md
|
|
│ └── ego-mgr/SKILL.md
|
|
├── dist/padded-cell/ # Build output
|
|
├── install.mjs # Installer
|
|
└── README.md
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# 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 `secret-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:
|
|
|
|
```bash
|
|
# 1. Before updating — export current build secret
|
|
~/.openclaw/bin/secret-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/secret-mgr admin init-from
|
|
|
|
# 4. Restart gateway
|
|
openclaw gateway restart
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Agent sets and gets private passwords (via pcexec)
|
|
secret-mgr set --key myservice --secret s3cret --username admin
|
|
secret-mgr get-secret --key myservice
|
|
secret-mgr get-username --key myservice
|
|
|
|
# Shared scope (.public)
|
|
secret-mgr set --public --key shared-api --secret s3cret
|
|
secret-mgr list --public
|
|
secret-mgr get-secret --public --key shared-api
|
|
|
|
# Use in shell commands (pcexec resolves and sanitizes)
|
|
curl -u "$(secret-mgr get-username --key myservice):$(secret-mgr get-secret --key myservice)" https://api.example.com
|
|
|
|
# Agent identity management (via pcexec)
|
|
ego-mgr add column name
|
|
ego-mgr set name "小智"
|
|
ego-mgr add public-column timezone --default UTC
|
|
ego-mgr show
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|