<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