@aporthq/aport-agent-guardrails 1.0.21 → 1.0.22

package/docs/frameworks/openclaw.md

@@ -1,69 +1,153 @@
 # APort Guardrails — OpenClaw
 
-OpenClaw is an open-source AI agent platform with a plugin system and built-in `before_tool_call` hooks. APort integrates via two paths:
-
-- **Native `guardrails:` config** (recommended) — OpenClaw's built-in `GuardrailProvider` interface loads `OAPGuardrailProvider` directly. No plugin needed.
-- **Plugin** (legacy, still works) — The `openclaw-aport` plugin registers a `before_tool_call` hook.
-
-Both paths use the same evaluator, passport, and policies.
+APort integrates with the current public OpenClaw release as a plugin. The plugin registers `before_tool_call` and blocks disallowed tools before execution. No OpenClaw core patch or native guardrail-provider merge is required.
 
 ## Quick start
 
 ```bash
-npm install @aporthq/aport-agent-guardrails-core
 npx @aporthq/aport-agent-guardrails openclaw
 ```
 
-The first command installs the provider. The second runs the passport wizard.
+If you already have a hosted passport on aport.io, pass the `agent_id` and skip local passport creation:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw ap_your_agent_id
+```
+
+The setup command:
+
+1. Chooses your OpenClaw config directory
+2. Creates a local passport or wires a hosted `agent_id`
+3. Installs the `openclaw-aport` plugin with `openclaw plugins install -l ...`
+4. Writes `plugins.entries.openclaw-aport` config into your OpenClaw config files
+5. Installs APort wrappers in `CONFIG_DIR/.skills/` for manual status checks and smoke tests
+
+After setup, start OpenClaw with the generated config:
+
+```bash
+openclaw gateway start --config ~/.openclaw/config.yaml
+```
+
+## What OpenClaw already gives you
+
+OpenClaw already ships meaningful runtime security controls:
+
+- sandboxing and OpenShell decide where tools run
+- tool policy decides which tools are callable
+- elevated execution gates host-level exec outside the sandbox
+- install-time scanning blocks obviously dangerous plugin bundles
+
+Those controls matter, and for many single-runtime deployments they may be enough.
+
+## What APort adds
+
+APort is useful when you need authorization and audit beyond OpenClaw's built-in containment and static tool policy:
+
+- per-agent identity and passport-based capability limits
+- parameter-aware authorization, not just tool allow/deny
+- local or hosted kill switch by suspending the passport
+- signed decision receipts and centralized audit in API mode
+- the same policy model across OpenClaw, CrewAI, DeerFlow, LangChain, and other runtimes
 
-## Config (native — recommended)
+In short: OpenClaw secures where tools run and which tools exist; APort secures whether a specific action is authorized for a specific agent right now.
 
-Add to your OpenClaw `config.yaml`:
+## Configuration
+
+The installer writes the plugin config for you. A minimal manual config looks like this:
 
 ```yaml
-guardrails:
+plugins:
   enabled: true
-  provider:
-    use: "@aporthq/aport-agent-guardrails-core"
-    config:
-      framework: "openclaw"
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        mode: api
+        passportFile: ~/.openclaw/aport/passport.json
+        apiUrl: https://api.aport.io
+        failClosed: true
+        allowUnmappedTools: true
 ```
 
-This loads `OAPGuardrailProvider` as a core guardrail service — runs before plugin hooks, cannot be bypassed by disabling a plugin.
+Hosted passport mode uses `agentId` instead of `passportFile`:
 
-## Config (plugin — legacy)
+```yaml
+plugins:
+  enabled: true
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        mode: api
+        agentId: ap_your_agent_id
+        apiUrl: https://api.aport.io
+        failClosed: true
+        allowUnmappedTools: true
+```
 
-The setup wizard (`npx @aporthq/aport-agent-guardrails openclaw`) installs the `openclaw-aport` plugin automatically. This registers a `before_tool_call` hook that calls the same evaluator.
+## Modes
 
-Both approaches are supported. The native config is recommended for new deployments.
+### API mode
 
-## How it works
+Best for production, signed decisions, and cloud kill switch workflows.
+
+- The plugin sends the request context and passport or `agentId` to `api.aport.io`
+- The API returns a signed decision
+- If your deployment needs authentication, set `apiKey` in plugin config
+
+### Local mode
+
+Best for privacy-sensitive or offline environments.
+
+- The plugin evaluates decisions with a built-in JavaScript evaluator
+- No `child_process` spawn is required
+- The installer still writes `guardrailScript` wrappers for manual smoke tests and legacy shell tooling, but current plugin versions do not depend on that script for local-mode enforcement
 
+## Manual install for development
+
+The public path is `npx @aporthq/aport-agent-guardrails openclaw`. If you are developing locally from a checkout, you can install the plugin directly:
+
+```bash
+openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
 ```
+
+Then add the same `plugins.entries.openclaw-aport` config shown above.
+
+## How it works
+
+```text
 Agent decides to use a tool
-        │
-        ▼
-  GuardrailService (native)     or     Plugin hook (legacy)
-        │                                      │
-        ▼                                      ▼
-  OAPGuardrailProvider ──────────────── same Evaluator
-        │
-  ┌─────┴─────┐
-  │           │
-ALLOW       DENY
-  │           │
-Tool runs   Agent sees denial reason
+        |
+        v
+OpenClaw fires before_tool_call
+        |
+        v
+APort plugin maps tool -> policy pack
+        |
+        v
+APort evaluates passport + limits (local JS evaluator or API)
+   |                    |
+   v                    v
+ allow                deny
+   |                    |
+Tool runs        Plugin returns block=true
 ```
 
-- **Provider class:** `OAPGuardrailProvider` from `@aporthq/aport-agent-guardrails-core`
-- **Passport:** `~/.openclaw/aport/passport.json` (created by wizard)
-- **Config:** `~/.openclaw/aport/config.yaml`
-- **Audit log:** `~/.openclaw/aport/audit.log`
+Common mappings include:
 
-## Suspend (kill switch)
+- `exec`, `exec.run` -> `system.command.execute.v1`
+- `git.create_pr`, `git.merge`, `git.push` -> `code.repository.merge.v1`
+- `message.send` -> `messaging.message.send.v1`
+- `read`, `view`, `glob` -> `data.file.read.v1`
+- `write`, `edit`, `multiedit` -> `data.file.write.v1`
 
-Local: set passport `status` to `suspended`. Remote: use API mode and suspend at [aport.io](https://aport.io).
+## Kill switch
+
+- Local passport: set `status` to `suspended` in `~/.openclaw/aport/passport.json`
+- Hosted passport: suspend the passport at aport.io
 
 ## Status
 
-Shipped; in production. Native `guardrails:` config available when [OpenClaw #46441](https://github.com/openclaw/openclaw/issues/46441) merges.
+Current public OpenClaw integration: plugin-based.
+
+Future path: if OpenClaw ships a native guardrail-provider seam upstream, APort can also plug into that provider path. That is not the current public default.

package/extensions/openclaw-aport/CHANGELOG.md

@@ -1,9 +1,15 @@
 # Changelog - APort OpenClaw Plugin
 
-## 1.0.21
-
 All notable changes to the APort OpenClaw plugin will be documented in this file.
 
+## [1.0.22] - 2026-04-13
+
+### Fixed
+- Replaced the old shell-spawning runtime with a scanner-safe JavaScript plugin runtime for local and API evaluation.
+- Added current OpenClaw compatibility metadata in `package.json` and aligned the hook return shape with the documented `before_tool_call` contract.
+- Kept `alwaysVerifyEachToolCall` as a deprecated manifest field so existing installs continue to load during upgrade.
+- Updated the public install and migration docs to match the plugin-based OpenClaw path.
+
 ## [1.0.21] - 2026-02-19
 
 ### Changed - OpenClaw 2026.2 Compatibility

package/extensions/openclaw-aport/MIGRATION.md

@@ -1,398 +1,45 @@
 # OpenClaw Plugin Migration Guide
 
-> **Note**: This is the **OpenClaw-specific plugin** within the broader [aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails) repository, which provides guardrails for multiple AI agent frameworks including LangChain, CrewAI, n8n, Cursor, and OpenClaw.
+This guide is for teams upgrading older APort OpenClaw installs to the current scanner-safe plugin bundle.
 
-## Breaking Changes in OpenClaw 2026.2
+## What changed
 
-The APort OpenClaw plugin has been updated to comply with OpenClaw 2026.2's new plugin architecture. If you're upgrading from an older version, please read this guide.
+Current plugin versions:
 
-## What Changed
+- ship JavaScript runtime files only (`index.js` plus helpers)
+- use a built-in JavaScript local evaluator instead of spawning `child_process`
+- call the hosted API directly in API mode
+- avoid source-linked `plugins.load.paths` entries that point into transient `npx` cache directories
 
-### Old Architecture (Pre-2026.2)
+## Recommended upgrade path
 
-```javascript
-// Old: Function-based plugin
-export default function (api) {
-  api.on("before_tool_call", async (event, ctx) => {
-    // handler code
-  });
-}
-```
-
-**Package.json:**
-```json
-{
-  "openclaw": {
-    "extensions": ["openclaw-aport"]  // ❌ String reference
-  }
-}
-```
-
-### New Architecture (2026.2+)
-
-```typescript
-// New: Object-based plugin with TypeScript
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-
-const plugin = {
-  id: "openclaw-aport",
-  name: "APort Guardrails",
-  description: "...",
-  configSchema: { /* JSON Schema */ },
-  register(api: OpenClawPluginApi) {
-    api.on("before_tool_call", async (event, ctx) => {
-      // handler code
-    });
-  },
-};
-
-export default plugin;
-```
-
-**Package.json:**
-```json
-{
-  "openclaw": {
-    "extensions": ["./index.ts"]  // ✅ Path to TypeScript file
-  }
-}
-```
-
-## Key Architectural Changes
-
-### 1. Plugin Structure
-
-| Old | New |
-|-----|-----|
-| Export function | Export object with `id`, `name`, `description`, `configSchema`, `register()` |
-| JavaScript (.js) | TypeScript (.ts) preferred |
-| Immediate execution | Lazy loading via `register()` method |
-
-### 2. Type Safety
-
-```typescript
-// Import OpenClaw types
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-
-// Config type safety
-interface APortPluginConfig {
-  mode?: "local" | "api";
-  agentId?: string;
-  passportFile?: string;
-  // ...
-}
-```
-
-### 3. Entry Point
-
-The `openclaw.extensions` field in `package.json` must now point to a file path:
-
-```json
-{
-  "openclaw": {
-    "extensions": ["./index.ts"]  // Path to entry file
-  }
-}
-```
-
-### 4. Dev Dependencies
-
-```json
-{
-  "devDependencies": {
-    "openclaw": ">=2026.2.0",
-    "@types/node": "^18.0.0",
-    "typescript": "^5.0.0"
-  }
-}
-```
-
-## Upgrading from Old Installation
-
-If you had the old plugin installed (OpenClaw < 2026.2), you need to **remove the old installation first** to avoid conflicts.
-
-### Step 1: Remove Old Plugin Configuration
-
-Edit your OpenClaw config file (usually `~/.openclaw/openclaw.json` or `~/.openclaw/config.json`) and remove:
-
-- `plugins.load.paths` — delete the entry pointing to `openclaw-aport`
-- `plugins.entries.openclaw-aport` — delete the entire block
-- `plugins.installs.openclaw-aport` — delete the entire block
-
-**Keep** `plugins.entries` intact if other plugins are configured (e.g. `whatsapp`).
-
-**Example — Before:**
-
-```json
-{
-  "plugins": {
-    "load": {
-      "paths": [
-        "/path/to/aport-agent-guardrails/extensions/openclaw-aport"
-      ]
-    },
-    "entries": {
-      "whatsapp": { "enabled": false },
-      "openclaw-aport": {
-        "enabled": true,
-        "config": { "mode": "api", "passportFile": "..." }
-      }
-    },
-    "installs": {
-      "openclaw-aport": {
-        "source": "path",
-        "sourcePath": "/path/to/openclaw-aport",
-        "installPath": "/path/to/openclaw-aport"
-      }
-    }
-  }
-}
-```
-
-**After:**
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "whatsapp": { "enabled": false }
-    }
-  }
-}
-```
-
-### Step 2: Restart Gateway
+Re-run the public setup command:
 
 ```bash
-openclaw gateway restart
+npx @aporthq/aport-agent-guardrails openclaw
 ```
 
-### Step 3: Verify Clean State
+That will:
 
-```bash
-openclaw gateway status
-openclaw plugins list
-```
-
-Confirm: no config errors, `openclaw-aport` not listed, RPC probe shows `ok`.
+1. Reinstall the plugin
+2. Refresh `plugins.entries.openclaw-aport`
+3. Remove stale source-linked `plugins.load.paths` and `plugins.installs.openclaw-aport` entries
+4. Refresh the APort wrappers under `CONFIG_DIR/.skills/`
 
-### Step 4: Install New Version
+## Development upgrade path
 
-Now install the updated plugin:
+If you are working from a local checkout:
 
 ```bash
-# Link for development (recommended)
 openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
-
-# Or install from directory
-openclaw plugins install /path/to/aport-agent-guardrails/extensions/openclaw-aport
-```
-
-This will:
-- Add the new plugin configuration to your config
-- Link to the `index.ts` entry point
-- Apply the new object-based plugin structure
-
-### Step 5: Configure Plugin
-
-Edit your OpenClaw config (now in YAML format, typically `~/.openclaw/config.yaml`):
-
-```yaml
-plugins:
-  enabled: true
-  entries:
-    openclaw-aport:
-      enabled: true
-      config:
-        mode: local  # or "api"
-        passportFile: ~/.openclaw/aport/passport.json
-        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
-        failClosed: true
-        allowUnmappedTools: true
-```
-
-### Step 6: Restart and Verify
-
-```bash
-openclaw gateway restart
-openclaw plugins list
-```
-
-You should see:
-
 ```
-┌──────────────┬──────────┬────────┬────────────────────────────────┬─────────┐
-│ Name         │ ID       │ Status │ Source                         │ Version │
-├──────────────┼──────────┼────────┼────────────────────────────────┼─────────┤
-│ APort        │ openclaw │ loaded │ ~/path/to/openclaw-aport/      │ 1.0.0   │
-│ Guardrails   │ -aport   │        │ index.ts                       │         │
-```
-
-## Fresh Installation (No Previous Version)
-
-### Verify Fresh Installation
-
-```bash
-# Link for development (recommended)
-openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
-
-# Then check
-openclaw plugins list
-```
-
-You should see:
-```
-┌──────────────┬──────────┬────────┬────────────────────────────────┬─────────┐
-│ Name         │ ID       │ Status │ Source                         │ Version │
-├──────────────┼──────────┼────────┼────────────────────────────────┼─────────┤
-│ APort        │ openclaw │ loaded │ ~/path/to/openclaw-aport/      │ 1.0.0   │
-│ Guardrails   │ -aport   │        │ index.ts                       │         │
-```
-
-Then configure in your `config.yaml` (see Configuration section above).
-
-## Configuration
-
-Configuration remains the same in your OpenClaw `config.yaml`:
-
-```yaml
-plugins:
-  enabled: true
-  entries:
-    openclaw-aport:
-      enabled: true
-      config:
-        mode: local  # or "api"
-        passportFile: ~/.openclaw/aport/passport.json
-        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
-        failClosed: true
-        allowUnmappedTools: true
-```
-
-## Testing
-
-Run the plugin unit tests:
-
-```bash
-cd extensions/openclaw-aport
-node test.js
-```
-
-Expected output:
-```
-# tests 21
-# pass 21
-# fail 0
-```
-
-## Backwards Compatibility
-
-The old `index.js` file is preserved for backwards compatibility with tests and older OpenClaw versions. However, OpenClaw 2026.2+ will use `index.ts`.
-
-## Troubleshooting
-
-### Old Plugin Still Loading After Upgrade
-
-**Symptom:**
-```
-[plugins] [APort] Loaded: ...
-```
-But you're seeing errors or the plugin isn't working correctly.
-
-**Solution:**
-The old plugin is still configured. Follow "Step 1: Remove Old Plugin Configuration" above and restart the gateway:
-
-```bash
-# 1. Edit config to remove old entries
-vim ~/.openclaw/openclaw.json  # or config.json
-
-# 2. Restart
-openclaw gateway restart
-
-# 3. Verify old plugin is gone
-openclaw plugins list  # Should NOT show openclaw-aport
-
-# 4. Reinstall new version
-openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
-```
-
-### Plugin Not Loading
-
-**Error:**
-```
-Config validation failed: plugins: plugin: extension entry escapes package directory
-```
-
-**Solution:**
-Ensure `package.json` has:
-```json
-{
-  "openclaw": {
-    "extensions": ["./index.ts"]  // Must be a file path, not a string reference
-  }
-}
-```
-
-### Config File Format Confusion
-
-OpenClaw 2026.2 uses YAML (`config.yaml`) for primary configuration, but plugin install metadata lives in JSON (`openclaw.json`):
-
-- **`~/.openclaw/config.yaml`** - Your main config (plugins.entries, passport paths, etc.)
-- **`~/.openclaw/openclaw.json`** - Plugin install metadata (managed by `openclaw plugins install`)
-
-When upgrading, edit the **JSON file** to remove old plugin entries, then use **YAML file** for new plugin configuration.
-
-### TypeScript Errors
-
-OpenClaw uses `jiti` to load TypeScript files at runtime, so you don't need to compile `.ts` to `.js`. However, for type checking during development:
-
-```bash
-npm install
-npx tsc --noEmit  # Check types without compiling
-```
-
-### Import Errors
-
-**Error:**
-```
-Cannot find module 'openclaw/plugin-sdk'
-```
-
-**Solution:**
-Ensure OpenClaw is installed:
-```bash
-npm install -g openclaw
-```
-
-Or add to devDependencies:
-```json
-{
-  "devDependencies": {
-    "openclaw": ">=2026.2.0"
-  }
-}
-```
-
-## Security Note
-
-OpenClaw 2026.2 introduced stricter security controls:
-- Agent-based access controls (`allowedAgents`)
-- Disabled plugin runtime command execution primitive
-- Explicit opt-in for deprecated features
-
-These changes don't affect the APort plugin's functionality but provide additional security layers at the OpenClaw level.
 
-## Resources
+Then re-run the installer or update `plugins.entries.openclaw-aport` in your config.
 
-- [OpenClaw Plugin Documentation](https://docs.openclaw.ai/tools/plugin)
-- [OpenClaw GitHub](https://github.com/openclaw/openclaw)
-- [APort Documentation](https://github.com/aporthq/aport-agent-guardrails)
+## Local mode
 
-## Version Compatibility
+Local mode still exists, but current plugin versions evaluate locally in JavaScript. The `guardrailScript` field remains for manual shell-based smoke tests and legacy tooling; the plugin no longer depends on it for local-mode enforcement.
 
-| OpenClaw Version | APort Plugin |
-|------------------|--------------|
-| < 2026.2 | Use old `index.js` (function-based) |
-| >= 2026.2 | Use new `index.ts` (object-based) |
+## If you previously installed from an old `npx` cache path
 
-The plugin now requires OpenClaw 2026.2.0 or later.
+Older setups could leave `openclaw.json` pointing at a transient `~/.npm/_npx/.../extensions/openclaw-aport` directory. Re-running the setup command cleans that up.