averecion-lite 1.3.0

package/README.md

@@ -0,0 +1,161 @@
+# Averecion Lite Adapter
+
+Lightweight, local-only governance adapter for OpenClaw and other AI agent frameworks.
+
+## Features
+
+- **One-Command Setup**: `npx averecion-lite init` does everything
+- **Policy Enforcement**: Allow/block skills based on a simple JSON policy
+- **Prompt Injection Detection**: Regex-based scanning for hazardous patterns
+- **Manual Confirmation**: CLI-based approval for high-risk actions
+- **Local Dashboard**: Single-page dashboard showing action metrics
+- **No Database**: Append-only JSON file with automatic rotation
+- **Secure by Default**: Shared secret required, localhost-only binding
+
+## Quick Start (Automated)
+
+```bash
+npx averecion-lite init
+```
+
+That's it! The command:
+1. ✅ Generates a secret key automatically
+2. ✅ Detects your OpenClaw config
+3. ✅ Adds the safety hooks
+4. ✅ Creates the default policy
+
+Then start the dashboard:
+```bash
+npx averecion-lite start
+```
+
+Visit `http://127.0.0.1:4321/clawguard` for the dashboard.
+
+## CLI Commands
+
+```bash
+npx averecion-lite init    # First-time setup
+npx averecion-lite start   # Start dashboard
+npx averecion-lite status  # Check configuration
+```
+
+## Usage
+
+### Basic Integration
+
+```typescript
+import { initLiteAdapter, beforeAction, afterAction } from "./index";
+
+await initLiteAdapter({
+  port: 4321,
+  enableCLIConfirm: true,
+});
+
+const result = await beforeAction({
+  tool: "shell.exec",
+  args: { command: "ls -la" },
+  plan: "List directory contents",
+});
+
+if (result.allowed) {
+  await afterAction(payload, result);
+}
+```
+
+### OpenClaw Hook
+
+```typescript
+import { createOpenClawHook, initLiteAdapter } from "./index";
+
+await initLiteAdapter();
+const hook = await createOpenClawHook();
+openclaw.registerHook(hook);
+```
+
+## API
+
+### GET /lite-metrics
+
+Returns aggregated metrics for the last 24 hours.
+
+**Headers Required:**
+- `X-Lite-Secret`: Your `LITE_ADAPTER_SECRET` value
+
+**Response:**
+```json
+{
+  "window": "24h",
+  "kpis": {
+    "approved": 142,
+    "blocked": 8,
+    "manualApproved": 5,
+    "highRiskIntercepts": 12,
+    "promptInjectionDetected": 1
+  },
+  "egressTop": [
+    {"host": "api.slack.com", "calls": 48}
+  ],
+  "skills": {"trusted": 18, "unknownBlocked": 3, "outdated": 0},
+  "instance": {
+    "reverseProxyHardened": true,
+    "dashboardLocalOnly": true,
+    "secretsEnvOnly": true
+  },
+  "timeline": {...},
+  "cost": {...},
+  "lastActions": [...]
+}
+```
+
+### GET /clawguard
+
+Serves the single-page dashboard HTML.
+
+### GET /health
+
+Health check endpoint (no auth required).
+
+## Security
+
+- **Shared Secret**: All API calls require `X-Lite-Secret` header
+- **Localhost Binding**: Server binds to `127.0.0.1` only
+- **No Proxy Trust**: Requests are rejected even if `X-Forwarded-For` indicates localhost
+- **No Secret Logging**: Secrets are never logged or exposed
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LITE_ADAPTER_SECRET` | (required) | Shared secret for authentication |
+| `LITE_PORT` | 4321 | Server port |
+| `LITE_HOST` | 127.0.0.1 | Server host |
+| `LITE_POLICY_PATH` | built-in | Custom policy file path |
+
+### Policy File
+
+Default location: `~/.averecion-lite/lite-policy.json`
+
+```json
+{
+  "allowedSkills": ["email.send", "calendar.create", "web.get", "file.read"],
+  "highRiskActions": ["shell.exec", "file.write", "network.post", "delete.*", "wallet.tx"],
+  "blockUnknownSkills": true
+}
+```
+
+## Storage
+
+Events are stored in `~/.averecion-lite/history.json`. The file is automatically rotated when it exceeds 5MB (keeps the most recent half of events).
+
+## Upgrade to Averecion Full
+
+Need enterprise features? Visit [averecion.com](https://averecion.com) for:
+
+- Cloud dashboard
+- Multi-agent orchestration
+- A/B testing
+- Compliance audit logs
+- SSO / RBAC
+- Enterprise support