@aporthq/aport-agent-guardrails 1.0.21 → 1.0.23

package/docs/QUICKSTART_OPENCLAW_PLUGIN.md

@@ -1,310 +1,48 @@
-# QuickStart: OpenClaw Plugin (Deterministic Enforcement)
+# QuickStart: OpenClaw Plugin
 
-**5-minute setup for deterministic, platform-level policy enforcement in OpenClaw.**
+Set up deterministic, platform-level guardrails for OpenClaw with one public command.
 
-**One command to get started** (recommended — no clone):
+## Quick start
 
 ```bash
-npx @aporthq/aport-agent-guardrails
+npx @aporthq/aport-agent-guardrails openclaw
 ```
 
-If you already have an agent_id from aport.io (e.g. after creating a passport there), run `npx @aporthq/aport-agent-guardrails openclaw <agent_id>` to use a hosted passport and skip the passport prompt. See [Hosted passport setup](HOSTED_PASSPORT_SETUP.md).
-
-This uses the [npm package](https://www.npmjs.com/package/@aporthq/aport-agent-guardrails): it downloads the package (policies + plugin), runs the setup wizard, installs the APort OpenClaw plugin, and runs a smoke test.
-
-Then start OpenClaw with the generated config (e.g. `openclaw gateway start --config ~/.openclaw/config.yaml`). The plugin will enforce policies on every tool call.
-
-**Alternative: clone the repo** (e.g. to hack on the code or use without npm):
-
-```bash
-git clone https://github.com/aporthq/aport-agent-guardrails.git && \
-  cd aport-agent-guardrails && \
-  git submodule update --init --recursive && \
-  ./bin/openclaw
-```
-
-*Already have the repo?* From the repo root run: `./bin/openclaw`
-
----
-
-## Why Use the Plugin?
-
-| Approach | Deterministic? | Bypass Risk | Security Level |
-|----------|----------------|-------------|----------------|
-| **OpenClaw Plugin** ✅ | Yes | None | 🟢 Secure |
-| AGENTS.md prompts | No | High | 🔴 Not secure |
-
-**Bottom line:** With the plugin, the platform enforces policy before every tool execution. The AI cannot bypass it.
-
----
-
-## Installation (Automatic)
-
-**Recommended:** Use `npx @aporthq/aport-agent-guardrails` (see top of this doc). If you cloned the repo instead, from the repo root run:
-
-```bash
-./bin/openclaw
-```
-
-The script will:
-1. Ask for your OpenClaw config directory (default `~/.openclaw`)
-2. Create your passport (OAP v1.0) there
-3. Prompt to install the APort OpenClaw plugin
-4. Ask for mode (default: **API**; or local) and generate `config.yaml` with plugin settings (passport path, guardrail script path, apiUrl for API mode)
-5. Install guardrail wrappers in the config dir’s `.skills/` (including `aport-guardrail-bash.sh` used by the plugin in local mode)
-6. **Update your passport** — the installer sets `allowed_commands: ["*"]` automatically so normal exec works with no manual editing. You only need to edit the passport later if you want to restrict commands more tightly.
-7. Run a **self-check** (guardrail invoked the same way OpenClaw will use it); if it’s denied, the script exits with a clear message so you know the setup is incomplete.
-8. Optionally install the APort skill and AGENTS.md rule, and run a smoke test
-9. Verify plugin installation
-
-**That's it!** Start OpenClaw with that config (e.g. `openclaw gateway start --config ~/.openclaw/config.yaml`). The plugin will enforce policies on every tool call; no extra steps required.
-
----
-
-## Installation (Manual)
-
-If you prefer manual installation:
-
-### 1. Create Passport
-
-```bash
-./bin/aport-create-passport.sh --output ~/.openclaw/aport/passport.json
-```
-
-### 2. Install Plugin
-
-```bash
-openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
-```
-
-### 3. Configure Plugin
-
-Create or edit `~/.openclaw/config.yaml`:
-
-```yaml
-plugins:
-  enabled: true
-  entries:
-    openclaw-aport:
-      enabled: true
-      config:
-        # Mode: "api" (default, recommended) or "local" (guardrail script, no network)
-        mode: api
-
-        # Passport file location
-        passportFile: ~/.openclaw/aport/passport.json
-
-        # For local mode: path to guardrail script
-        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
-
-        # Fail-closed: block on error (default: true)
-        failClosed: true
-```
-
-For **API mode (default)**, set:
-```yaml
-        mode: api
-        apiUrl: https://api.aport.io
-```
-Set `APORT_API_KEY` in the environment if your API requires auth. Do not put `${APORT_API_KEY}` in the config file (OpenClaw will require the var to exist at load time).
-
-### 4. Install Guardrail Scripts (local mode only)
-
-If you **did not** run `./bin/openclaw`, you need the guardrail script for local mode. If you **did** run the setup script, it already created `CONFIG_DIR/.skills/aport-guardrail-bash.sh`; skip this step.
-
-Otherwise:
-
-```bash
-mkdir -p ~/.openclaw/.skills
-# Create wrapper that points to this repo (replace /path/to with real path)
-cat > ~/.openclaw/.skills/aport-guardrail-bash.sh << 'EOF'
-#!/bin/bash
-APORT_REPO_ROOT="/path/to/aport-agent-guardrails"
-export OPENCLAW_PASSPORT_FILE="${OPENCLAW_PASSPORT_FILE:-$HOME/.openclaw/aport/passport.json}"
-export OPENCLAW_DECISION_FILE="${OPENCLAW_DECISION_FILE:-$HOME/.openclaw/aport/decision.json}"
-exec "$APORT_REPO_ROOT/bin/aport-guardrail-bash.sh" "$@"
-EOF
-chmod +x ~/.openclaw/.skills/aport-guardrail-bash.sh
-```
-
-### 5. Verify Installation
+Hosted passport:
 
 ```bash
-# Check plugin is installed
-openclaw plugins list | grep openclaw-aport
-
-# Should show: openclaw-aport (enabled)
-```
-
----
-
-## How It Works
-
-```
-User → AI: "Delete all log files"
-         ↓
-    OpenClaw: AI wants to use tool "exec.run"
-         ↓
-    Platform: Fires before_tool_call hook
-         ↓
-  APort Plugin: Maps "exec.run" → "system.command.execute.v1"
-         ↓
-  APort Plugin: Calls guardrail script/API
-         ↓
-    Guardrail: Evaluates against passport + limits
-         ↓
-   ┌──────────┴──────────┐
-   │                     │
- ALLOW                 DENY
-   │                     │
-   ↓                     ↓
-Tool executes      Returns { block: true, blockReason }
-                         ↓
-                   OpenClaw throws error
-                         ↓
-                   Tool NEVER executes
+npx @aporthq/aport-agent-guardrails openclaw ap_your_agent_id
 ```
 
-**Key:** The platform enforces policy. The AI cannot skip this check.
+No repo clone is required.
 
----
+## What the setup command does
 
-## Testing
+1. Prompts for 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 plugin config into `config.yaml` and `openclaw.json`
+5. Installs `aport-*` wrappers under `CONFIG_DIR/.skills/`
+6. Runs a smoke test so you know the setup is complete
 
-### 1. Start OpenClaw with Plugin
+After setup, start OpenClaw with the generated config:
 
 ```bash
 openclaw gateway start --config ~/.openclaw/config.yaml
 ```
 
-### 2. Test Allowed Action
-
-Try a simple command that should be allowed:
-
-```bash
-# Via OpenClaw agent
-"Run: node --version"
-```
-
-Expected: Command executes (allowed by passport limits)
-
-### 3. Test Denied Action
-
-Try a command that exceeds your passport limits:
-
-```bash
-# Via OpenClaw agent
-"Delete all files in /tmp"
-```
-
-Expected: Tool blocked with message:
-```
-🛡️ APort Policy Denied
+## What gets installed
 
-Policy: system.command.execute.v1
-Reason: Command exceeds allowed scope
-
-To override, update your passport at: ~/.openclaw/aport/passport.json (or ~/.openclaw/passport.json for legacy)
-```
-
----
+- `~/.openclaw/aport/passport.json` for local passport mode
+- `~/.openclaw/config.yaml` with `plugins.entries.openclaw-aport`
+- `~/.openclaw/openclaw.json` with matching plugin entry
+- `~/.openclaw/.skills/aport-*` wrappers for manual checks and shell tooling
 
 ## Modes
 
-**API mode** is still the default and recommended. **Local mode** now has full parity with API for exec mapping (fixed); both evaluate the same policies. Messaging runs at assurance L0 by default.
-
-### API Mode (default, recommended)
-
-**Best for:** Production, full OAP policy (JSON Schema, assurance, evaluation rules), signed decisions, cloud kill switch, audit logs.
-
-```yaml
-config:
-  mode: api
-  passportFile: ~/.openclaw/aport/passport.json
-  apiUrl: https://api.aport.io
-```
-Set `APORT_API_KEY` in the environment only if your API requires auth.
-
-**How it works:**
-- Plugin loads local passport
-- Sends passport + context to APort API
-- API evaluates (passport NOT stored, stateless)
-- Returns signed decision
-- **Network required**
-
-### Local Mode
-
-**Best for:** Privacy, offline use, no network dependency
-
-```yaml
-config:
-  mode: local
-  passportFile: ~/.openclaw/aport/passport.json
-  guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
-```
-
-**How it works:**
-- Plugin calls local bash script
-- Script evaluates policy using local passport (subset of OAP; see [Verification methods](VERIFICATION_METHODS.md))
-- Returns decision (exit 0 = allow, exit 1 = deny)
-- **No network required**
-
----
-
-## Troubleshooting
-
-### Plugin not loading
-
-```bash
-# Check plugin list
-openclaw plugins list
-
-# Should show: openclaw-aport (enabled)
-```
-
-If not listed:
-1. Verify installation: `openclaw plugins install -l /path/to/extensions/openclaw-aport`
-2. Check config.yaml has `plugins.entries.openclaw-aport.enabled: true`
-3. Restart OpenClaw gateway
-
-### Tools not being blocked
-
-Check:
-1. **Plugin enabled?** `openclaw plugins list` should show `openclaw-aport (enabled)`
-2. **Tool mapped?** See tool-to-policy mapping in plugin README
-3. **Passport allows it?** The installer sets `allowed_commands: ["*"]` by default. If you intentionally tightened the allowlist, re-add the commands you need to `limits.system.command.execute.allowed_commands` in your passport.
-4. **Script working?** Test directly:
-   ```bash
-   ~/.openclaw/.skills/aport-guardrail-bash.sh system.command.execute '{"command":"ls"}'
-   ```
-
-### Error: "Failed to run guardrail script"
-
-Check:
-1. Script exists: `ls -l ~/.openclaw/.skills/aport-guardrail-bash.sh`
-2. Script executable: `chmod +x ~/.openclaw/.skills/aport-guardrail-bash.sh`
-3. Script works: Run test command above
-
-### Guardrail DENY / `oap.passport_version_mismatch`
-
-If the guardrail denies every call and `~/.openclaw/aport/decision.json` (or `~/.openclaw/decision.json`) shows reason `oap.passport_version_mismatch` ("Passport spec version is 'unknown', expected 'oap/1.0'"):
-
-1. **Passport must have `spec_version: "oap/1.0"`** (OAP spec). If your passport has only `"version": "1.0.0"` in metadata and no top-level `spec_version`, it was created by an older or non–spec-compliant tool.
-2. **Limits must be nested per capability.** The verifier expects e.g. `limits["system.command.execute"]` with `allowed_commands`, `blocked_patterns`, not a flat `limits.allowed_commands` at the top level.
-
-**Fix:** Re-run the installer so it can normalize the passport:
-
-```bash
-npx @aporthq/aport-agent-guardrails
-```
-
-Choose to overwrite the existing passport when prompted, or run the wizard with `--output` to a new file. The installer now ensures `spec_version: "oap/1.0"` and nested limits. If you prefer to fix the file manually, add `"spec_version": "oap/1.0"` at the top level and move any top-level `allowed_commands` / `blocked_patterns` under `limits["system.command.execute"]`. See [agent-passport/spec/oap](https://github.com/aporthq/agent-passport/tree/main/spec/oap) for the canonical schema.
-
----
-
-## Configuration Reference
+### API mode
 
-### Minimum Configuration (API mode — default)
+Recommended for production.
 
 ```yaml
 plugins:
@@ -319,33 +57,11 @@ plugins:
         failClosed: true
 ```
 
-### Full Configuration (API mode)
+Hosted passports use `agentId` instead of `passportFile`.
 
-```yaml
-plugins:
-  enabled: true
-  entries:
-    openclaw-aport:
-      enabled: true
-      config:
-        # Mode: "api" (default) or "local"
-        mode: api
-
-        # Passport file location
-        passportFile: ~/.openclaw/aport/passport.json
-
-        # For local mode: path to guardrail script
-        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
-
-        # For API mode: APort API endpoint
-        apiUrl: https://api.aport.io  # or your self-hosted API URL
-        # Optional: set APORT_API_KEY in the environment if your API requires auth
-
-        # Fail-closed: block on error (default: true)
-        failClosed: true
-```
+### Local mode
 
-### Minimum Configuration (Local mode)
+Best for offline or privacy-sensitive workflows.
 
 ```yaml
 plugins:
@@ -356,115 +72,33 @@ plugins:
       config:
         mode: local
         passportFile: ~/.openclaw/aport/passport.json
-        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
         failClosed: true
 ```
 
----
+Current plugin versions use a built-in JavaScript evaluator in local mode. The setup command still installs `aport-guardrail-bash.sh` for manual smoke tests and shell tooling, but the plugin does not depend on `child_process` or the bash script for local-mode enforcement.
 
-## Tool-to-Policy Mapping
+## Development install
 
-The plugin automatically maps OpenClaw tool names to APort policy packs:
-
-| OpenClaw Tool | APort Policy |
-|---------------|--------------|
-| `git.create_pr`, `git.merge`, `git.push` | `code.repository.merge.v1` |
-| `exec.run`, `system.command.*`, `bash` | `system.command.execute.v1` |
-| `message.send`, `messaging.*` | `messaging.message.send.v1` |
-| `mcp.*` | `mcp.tool.execute.v1` |
-| `session.create` | `agent.session.create.v1` |
-| `tool.register` | `agent.tool.register.v1` |
-| `payment.refund` | `finance.payment.refund.v1` |
-| `payment.charge` | `finance.payment.charge.v1` |
-| `data.export` | `data.export.create.v1` |
-
-Unmapped tools are allowed (fail-open for flexibility).
-
----
-
-## Security Considerations
-
-### Fail-Closed by Default
-
-By default, `failClosed: true` means **any error blocks the tool**:
-- Script not found → BLOCK
-- API unreachable → BLOCK
-- Invalid passport → BLOCK
-
-This is secure-by-default. To fail-open (not recommended):
-
-```yaml
-config:
-  failClosed: false  # Allow on error (NOT RECOMMENDED)
-```
+If you are developing from a local checkout:
 
-### Plugin Trust
-
-Plugins run **in-process** with full access to OpenClaw. Only install from trusted sources:
-- Official APort plugin (this)
-- Your own forks/modifications
-
-Use `plugins.allow` allowlist in config.yaml:
-
-```yaml
-plugins:
-  allow:
-    - openclaw-aport
-    - your-other-trusted-plugin
+```bash
+openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
 ```
 
-### Bypass Prevention
-
-**With plugin:** AI **cannot** bypass policy enforcement. The platform calls `before_tool_call` before every tool.
-
-**Without plugin (AGENTS.md only):** AI **can** bypass via:
-- Prompt injection
-- Forgetting to call guardrail
-- Deciding action is "safe"
-
-**Bottom line:** Plugin = deterministic. AGENTS.md = best-effort (not secure).
-
----
-
-## Next Steps
-
-1. **Run the setup (once):** From repo root: `./bin/openclaw`. Use the default config dir or choose a path.
-2. **Choose "yes"** when prompted to install the plugin.
-3. **Start OpenClaw** with the generated config: `openclaw gateway start --config <your-config-dir>/config.yaml` (e.g. `~/.openclaw/config.yaml`).
-4. **Test enforcement:** Run the agent; try an allowed action (e.g. `node --version`) and one that should be blocked by your passport (e.g. `rm -rf /`). The plugin blocks before the tool runs.
-5. **Customize passport:** Edit `<config-dir>/aport/passport.json` (or `<config-dir>/passport.json` for legacy) to adjust limits and allowed commands.
-
----
-
-## Support
-
-- **Full documentation:** [`extensions/openclaw-aport/README.md`](../extensions/openclaw-aport/README.md)
-- **Issues:** [GitHub Issues](https://github.com/aporthq/aport-agent-guardrails/issues)
-- **Discord:** [discord.gg/aport](https://discord.gg/aport)
-
----
-
-## Summary
-
-✅ **One command:** Run `./bin/openclaw` from the repo root to create passport, install plugin, write config and wrappers, and verify. You only need this once per config dir.
-✅ **Deterministic enforcement:** The plugin runs before every tool; the platform enforces, the AI cannot bypass.
-✅ **Fail-closed:** Blocks on error by default.
-✅ **API (default) or local:** Full OAP via API, or local script for offline/privacy.
-✅ **Zero OpenClaw core changes:** Uses the existing OpenClaw plugin API.
+Public users should prefer the `npx @aporthq/aport-agent-guardrails openclaw` path.
 
-**After setup, start OpenClaw with the generated config—your agent is then secured by APort policy.**
+## Runtime behavior
 
----
+On every tool call:
 
-## How it all fits together
+1. OpenClaw fires `before_tool_call`
+2. APort maps the OpenClaw tool to an OAP policy pack
+3. APort evaluates the passport and limits
+4. `allow` lets the tool run
+5. `deny` returns `block: true` and the tool never executes
 
-| Step | What happens |
-|------|----------------|
-| You run `./bin/openclaw` | Script asks for config dir, creates passport, installs plugin, writes `config.yaml`, installs wrappers in `<config-dir>/.skills/`, and **updates the passport** with default `allowed_commands` (bash, sh, ls, mkdir, npm, etc.) so normal exec works. |
-| `config.yaml` | Contains `passportFile` and `guardrailScript` pointing to `<config-dir>/aport/passport.json` and `<config-dir>/.skills/aport-guardrail-bash.sh`. |
-| Passport allowlist | The installer sets `allowed_commands: ["*"]` automatically. No manual editing needed unless you want to restrict commands. |
-| Wrapper script | `<config-dir>/.skills/aport-guardrail-bash.sh` is a small script that calls this repo’s `bin/aport-guardrail-bash.sh` with the same args and env (passport path, etc.). |
-| You start OpenClaw | `openclaw gateway start --config <config-dir>/config.yaml` (or use that config when running the agent). |
-| On every tool call | OpenClaw runs the plugin’s `before_tool_call` hook → plugin calls the guardrail script with tool name and params → script evaluates against passport and policy → allow = tool runs, deny = plugin returns `block: true` and the tool never runs. |
+## Notes
 
-**So: one run of `./bin/openclaw` is all you need.** No manual editing of config or wrapper paths if you use the default config dir.
+- Current public OpenClaw integration is plugin-based
+- No upstream native guardrail-provider merge is required for this path
+- If setup cannot install the plugin, it now stops immediately instead of writing broken config

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.21 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.23 (see [CHANGELOG.md](../CHANGELOG.md)).
 
 We keep **one version number** across all published packages (Node core, Python core, and every framework adapter). That avoids “core is 1.2 but CLI is 0.9” and keeps the story simple for users and support.
 
@@ -52,7 +52,8 @@ So: **root = CLI/setup**; **core = library**. We publish core so that (1) the ad
    ```
 5. **CI (`.github/workflows/release.yml`)**: on tag push `v*`:
    - **publish-npm**: publishes the **root** package `@aporthq/aport-agent-guardrails` (CLI) and workspace packages `@aporthq/aport-agent-guardrails-core`, `-langchain`, `-crewai`, `-cursor`, `-claude-code`, and `@aporthq/openclaw-aport` to npm. The **n8n** package is not published yet (coming soon). Uses `NPM_TOKEN` secret.
-   - **publish-python**: builds and publishes `aport-agent-guardrails`, `aport-agent-guardrails-langchain`, and `aport-agent-guardrails-crewai` to PyPI (uses `PYPI_TOKEN` secret). Skips upload if aport-agent-guardrails version already exists.
+   - **publish-python**: builds and publishes `aport-agent-guardrails`, `aport-agent-guardrails-langchain`, and `aport-agent-guardrails-crewai` to PyPI (uses `PYPI_TOKEN` secret). Uploads use `--skip-existing`, so reruns or recovery releases can still publish any missing Python artifacts for the same version.
+   - **workflow_dispatch**: supports release recovery for an existing version after workflow fixes land on `main`.
    - **create-release**: creates the GitHub Release with install notes for both ecosystems.
 
    **PyPI**: In [PyPI project settings](https://pypi.org/help/#project-urls), set Repository and (if using trusted publishing) add this repo and workflow name **Release**. Otherwise configure the `PYPI_TOKEN` secret in the GitHub repo.

package/docs/TOOL_POLICY_MAPPING.md

@@ -1,8 +1,8 @@
 # Tool → policy pack mapping
 
-OpenClaw (or any caller) invokes the guardrail with a **tool name** and **context JSON**. The guardrail maps the tool name to a **policy pack** in `external/aport-policies/` and evaluates the request against that policy and the passport.
+The shell/API guardrail entrypoints invoke the guardrail with a **tool name** and **context JSON**. The guardrail maps the tool name to a **policy pack** in `external/aport-policies/` and evaluates the request against that policy and the passport.
 
-This mapping is implemented in `bin/aport-guardrail-api.sh` and `bin/aport-guardrail-bash.sh`. The table below is the single source of truth for documentation.
+This mapping is implemented in `bin/aport-guardrail-api.sh` and `bin/aport-guardrail-bash.sh`. The OpenClaw plugin has its own host-specific mapping in `extensions/openclaw-aport/tool-mapping.js`.
 
 ## Mapping table