@aporthq/aport-agent-guardrails 1.0.8

package/docs/TOOL_POLICY_MAPPING.md

@@ -0,0 +1,46 @@
+# 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.
+
+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.
+
+## Mapping table
+
+| Tool name (pattern) | Policy pack ID | Policy location |
+|---------------------|----------------|------------------|
+| `git.create_pr`, `git.merge`, `git.push`, `git.*` | `code.repository.merge.v1` | `external/aport-policies/code.repository.merge.v1/` |
+| `exec.run`, `exec.*`, `system.command.*`, `system.*` | `system.command.execute.v1` | `local-overrides` or API |
+| `message.send`, `message.*`, `messaging.*` | `messaging.message.send.v1` | `external/aport-policies/messaging.message.send.v1/` |
+| `mcp.tool.*`, `mcp.*` | `mcp.tool.execute.v1` | API / evaluator |
+| `agent.session.*`, `session.create`, `session.*` | `agent.session.create.v1` | API / evaluator |
+| `agent.tool.*`, `tool.register`, `tool.*` | `agent.tool.register.v1` | API / evaluator |
+| `payment.refund`, `payment.*`, `finance.payment.refund` | `finance.payment.refund.v1` | `external/aport-policies/finance.payment.refund.v1/` |
+| `payment.charge`, `finance.payment.charge` | `finance.payment.charge.v1` | `external/aport-policies/finance.payment.charge.v1/` |
+| `database.write`, `database.*`, `data.export` | `data.export.create.v1` | `external/aport-policies/data.export.create.v1/` |
+
+**Unknown tool:** In the **bash/API guardrail script**, an unknown tool name results in deny (exit 1). In the **OpenClaw plugin**, unmapped tools are **allowed** by default so custom skills and ClawHub tools work; set `allowUnmappedTools: false` in plugin config for strict (block unmapped).
+
+## How OpenClaw uses it
+
+1. OpenClaw (or your integration code) decides to run a tool, e.g. `system.command.execute` with `{"command":"npm install"}`.
+2. Before executing, it calls the guardrail script with that tool name and context:
+   ```bash
+   ~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"npm install"}'
+   ```
+3. The script maps `system.command.execute` → `system.command.execute.v1`, loads the passport and policy (or calls the API), and evaluates.
+4. Exit 0 = allow, exit 1 = deny. Decision details are in `~/.openclaw/decision.json` (or your configured path).
+
+## Adding or changing mappings
+
+To add a new tool → policy mapping, edit the `case` block in:
+
+- `bin/aport-guardrail-api.sh`
+- `bin/aport-guardrail-bash.sh`
+
+and add a new pattern and policy pack ID. The policy pack must exist under `external/aport-policies/<pack_id>/` (or in local-overrides / API).
+
+## Reference
+
+- OAP spec: `external/aport-spec/`
+- Policy packs: `external/aport-policies/`
+- AGENTS.md example: [AGENTS.md.example](AGENTS.md.example)

package/docs/UPGRADE.md

@@ -0,0 +1,46 @@
+# Upgrade Guide
+
+## Upgrading from 0.1.0 to 1.0.0
+
+### Breaking Changes
+None - 1.0.0 is the first production release.
+
+### New Features
+- OpenClaw plugin with `before_tool_call` enforcement
+- API mode support (in addition to local mode)
+- Enhanced exec handling with recursive guardrail detection
+- Improved error messages with OAP codes
+
+### Migration Steps
+
+**If upgrading from 0.1.0:**
+
+1. Update your installation:
+   ```bash
+   git pull
+   git submodule update --init --recursive
+   ```
+
+2. Re-run setup to install plugin:
+   ```bash
+   ./bin/openclaw
+   ```
+
+3. Update OpenClaw config (if using plugin):
+   ```yaml
+   plugins:
+     entries:
+       openclaw-aport:
+         enabled: true
+         config:
+           mode: local  # or "api"
+           passportFile: ~/.openclaw/passport.json
+   ```
+
+4. Verify passport has `allowed_commands`:
+   ```bash
+   jq '.limits.system.command.execute.allowed_commands' ~/.openclaw/passport.json
+   ```
+   If empty or missing, re-run passport wizard or add manually.
+
+**No other changes required.**

package/docs/VERIFICATION_METHODS.md

@@ -0,0 +1,97 @@
+# Verification methods: Local vs API
+
+This doc compares how policy is evaluated in **local mode** (bash guardrail script) vs **API mode** (APort cloud or self-hosted agent-passport using the generic evaluator). It also summarizes the four ways you can run the guardrail (standalone bash, standalone API, plugin + local, plugin + API).
+
+---
+
+## Summary: when to use which
+
+| Method | Best for | Robustness | Network |
+|--------|----------|------------|---------|
+| **API (default)** | Production, full OAP parity, new policy rules without code changes | Full: JSON Schema, assurance, regions, taxonomy, MCP, evaluation_rules from policy JSON, signed decisions | Yes (api.aport.io or self-hosted) |
+| **Local (bash)** | Privacy, offline, air-gapped, or no API key | Core checks only; same policy packs but hand-coded per policy; new rules need script updates | No |
+
+**Recommendation:** Use **API mode** (default in `./bin/openclaw`) for full policy fidelity and future policy packs. Use **local mode** when you must avoid the network or run fully offline.
+
+---
+
+## Four ways to run the guardrail
+
+| # | Method | How | Typical use |
+|---|--------|-----|-------------|
+| 1 | **Standalone bash** | `OPENCLAW_PASSPORT_FILE=... ./bin/aport-guardrail-bash.sh <tool> '<context_json>'` | Scripts, CI, manual checks |
+| 2 | **Standalone API** | `./bin/aport-guardrail-api.sh <tool> '<context_json>'` with `APORT_API_URL` | Same as above, but evaluation in cloud |
+| 3 | **Plugin + local** | OpenClaw `before_tool_call` → plugin spawns `aport-guardrail-bash.sh` | OpenClaw with no API / offline |
+| 4 | **Plugin + API** | OpenClaw `before_tool_call` → plugin calls APort API | OpenClaw with full OAP (default) |
+
+All four produce OAP v1.0–shaped decisions (allow, reasons, policy_id, etc.). The **evaluation logic** differs between local (bash) and API (generic evaluator).
+
+---
+
+## Local evaluator (bash) vs API generic evaluator
+
+The **APort API** (and self-hosted agent-passport) uses a **generic evaluator** that loads policy JSON and runs a full OAP pipeline. The **local guardrail** in this repo (`bin/aport-guardrail-bash.sh`) implements a **subset** of that pipeline in bash + jq.
+
+### What the API generic evaluator does (full OAP)
+
+1. **Passport status** — suspended/revoked → deny  
+2. **Required context (JSON Schema)** — validates `required_context` from policy JSON against the request  
+3. **Capabilities** — passport must have required capabilities (e.g. `system.command.execute`, `messaging.send`)  
+4. **Assurance level** — `min_assurance` from policy (e.g. L2) vs passport assurance  
+5. **Limits** — uses `evaluation_rules` from policy JSON (expression + custom_validator); supports capability-scoped limits, DB-backed rate limits, idempotency  
+6. **Regions** — `requires_regions` from policy  
+7. **Taxonomy** — policy-defined taxonomy checks  
+8. **MCP** — MCP allowlist/validation when defined  
+9. **Custom evaluation rules** — runs each `evaluation_rules` entry (expression or custom_validator) from the policy pack  
+10. **Signed decisions** — Ed25519 signatures, optional chained audit  
+
+Reference: [agent-passport generic-evaluator](https://github.com/aporthq/agent-passport) (`functions/utils/policy/generic-evaluator.ts`).
+
+### What the local (bash) evaluator does
+
+1. **Passport status** — local verify checks passport status first; if `status` is not `active` (e.g. `suspended` or `revoked`) → deny with `oap.passport_suspended`. Passport is the source of truth (no separate kill-switch file).  
+2. **Passport load** — read passport JSON; invalid or missing → deny  
+3. **Passport status** — `status !== "active"` → deny  
+4. **Spec version** — must be `oap/1.0`  
+5. **Tool → policy mapping** — fixed `case` (e.g. `exec.*`/`system.*` → `system.command.execute.v1`, `messaging.*` → `messaging.message.send.v1`)  
+6. **Capabilities** — passport must list required capability (with alias e.g. `messaging.message.send` → `messaging.send`)  
+7. **Policy-specific limits (hand-coded):**  
+   - **code.repository.merge** — PR size (`max_pr_size_kb`), `allowed_repos`, `allowed_base_branches`  
+   - **system.command.execute** — `allowed_commands` (prefix or `*`), `blocked_patterns`  
+   - **messaging.message.send** — `allowed_recipients` (optional)  
+8. **Decision output** — OAP-shaped decision (allow, reasons, policy_id, passport_digest, content_hash, chain)  
+9. **No** JSON Schema validation of context  
+10. **No** assurance, regions, taxonomy, MCP, or generic `evaluation_rules` from policy JSON  
+
+So: **local is robust enough for the core policies** (exec, messaging, repo merge) for allowlist/blocklist and the limits implemented in bash. It is **not** a full reimplementation of the generic evaluator. New policy packs or new rules in existing packs (e.g. `working_directory`, `environment_variables` in system.command.execute) require either API mode or updates to the bash script.
+
+---
+
+## Feature comparison (local vs API)
+
+| Feature | Local (bash) | API (generic evaluator) |
+|---------|--------------|--------------------------|
+| Passport status check | ✅ | ✅ |
+| Kill switch | ✅ (file-based) | N/A (handled by registry/suspend) |
+| Capability check | ✅ (with messaging alias) | ✅ |
+| JSON Schema required_context | ❌ | ✅ |
+| Assurance level | ❌ | ✅ |
+| Regions | ❌ | ✅ |
+| Taxonomy | ❌ | ✅ |
+| MCP validation | ❌ | ✅ |
+| Limits from policy JSON | Hand-coded subset only | ✅ Full (evaluation_rules, custom_validators) |
+| system.command.execute | allowed_commands, blocked_patterns | + execution_time, working_directory, env (if in policy) |
+| code.repository.merge | PR size, allowed_repos, allowed_base_branches | Same + path_allowlist, require_review if in policy |
+| messaging.message.send | allowed_recipients | + rate limits (msgs_per_min/day), channel allowlist (if in policy) |
+| New policy packs | Requires bash changes | Load from policy JSON |
+| Signed decisions | Local-unsigned only | Ed25519 signed (cloud) |
+| Rate limits / idempotency | ❌ | ✅ (when API uses DB) |
+
+---
+
+## Conclusion
+
+- **Local (bash):** Useful for privacy, offline, and the core use cases (exec allowlist/blocklist, messaging recipient, repo/PR limits). For full OAP parity and future policy packs, use **API mode**.
+- **API (default):** Recommended for production and when you want the same behavior as [APort in Goose](https://raw.githubusercontent.com/aporthq/.github/refs/heads/main/profile/APORT_GOOSE_ARCHITECTURE.md) and the full generic evaluator (JSON Schema, assurance, regions, evaluation_rules, signed decisions).
+
+The installer (`./bin/openclaw`) defaults to **API mode**; choose local only when you need to run without the network.

package/docs/assets/README.md

@@ -0,0 +1,8 @@
+# Assets for docs and README
+
+- **Porter (mascot):** Use SVGs and the interactive playground from [APort Brand — Meet Porter](https://aport.io/brand-mascot-agent/). You can download the page or copy the mascot SVGs for use in docs or the main README.
+- **Demo GIF:** Add a short GIF here (e.g. `porter-demo.gif` or `guardrail-demo.gif`) showing:
+  - Terminal: one ALLOW and one DENY from the guardrail, or
+  - Plugin config + passport snippet, or
+  - Porter verifying a command (from the brand page).
+  Then reference it in the root README, e.g. `![Demo](docs/assets/porter-demo.gif)`.

package/docs/assets/porter.svg

@@ -0,0 +1,54 @@
+<svg width="120" height="120" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+  <defs>
+    <filter id="softShadow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur in="SourceAlpha" stdDeviation="2"/>
+      <feOffset dx="0" dy="2" result="offsetblur"/>
+      <feComponentTransfer>
+        <feFuncA type="linear" slope="0.15"/>
+      </feComponentTransfer>
+      <feMerge>
+        <feMergeNode/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+    <radialGradient id="innerGlow" cx="50%" cy="40%" r="60%">
+      <stop offset="0%" stop-color="white" stop-opacity="0.2"/>
+      <stop offset="100%" stop-color="white" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <circle cx="50" cy="50" r="48" fill="#0A84FF" opacity="0.05"/>
+  <rect x="30" y="35" width="40" height="40" rx="20" fill="#007AFF" filter="url(#softShadow)"/>
+  <rect x="30" y="35" width="40" height="40" rx="20" fill="url(#innerGlow)"/>
+  <rect x="33" y="38" width="34" height="34" rx="17" fill="#F5F5F7" opacity="0.12"/>
+  <line x1="38" y1="48" x2="54" y2="48" stroke="#0A84FF" stroke-width="1" opacity="0.3"/>
+  <line x1="38" y1="52" x2="62" y2="52" stroke="#0A84FF" stroke-width="1" opacity="0.3"/>
+  <line x1="38" y1="56" x2="58" y2="56" stroke="#0A84FF" stroke-width="1" opacity="0.3"/>
+  <g transform="translate(0, -2)">
+    <ellipse cx="50" cy="35" rx="22" ry="11" fill="#1D1D1F" opacity="0.9"/>
+    <ellipse cx="50" cy="37" rx="26" ry="6" fill="#1D1D1F" opacity="0.7"/>
+  </g>
+  <ellipse cx="50" cy="30" rx="6" ry="7" fill="#FF9500" opacity="0.9"/>
+  <text x="50" y="33" text-anchor="middle" font-size="5" fill="white" font-weight="bold">AP</text>
+  <ellipse cx="42" cy="48" rx="4" ry="4" fill="white" opacity="0.95"/>
+  <circle cx="42" cy="48" r="2.5" fill="#1D1D1F"/>
+  <ellipse cx="58" cy="48" rx="4" ry="4" fill="white" opacity="0.95"/>
+  <circle cx="58" cy="48" r="2.5" fill="#1D1D1F"/>
+  <circle cx="40.5" cy="46.5" r="0.8" fill="white" opacity="0.9"/>
+  <circle cx="56.5" cy="46.5" r="0.8" fill="white" opacity="0.9"/>
+  <ellipse cx="35" cy="56" rx="3.5" ry="2.5" fill="#FF9AA2" opacity="0.25"/>
+  <ellipse cx="65" cy="56" rx="3.5" ry="2.5" fill="#FF9AA2" opacity="0.25"/>
+  <path d="M 42 58 Q 50 63 58 58" fill="none" stroke="#1D1D1F" stroke-width="2" stroke-linecap="round" opacity="0.9"/>
+  <ellipse cx="50" cy="66" rx="8" ry="6" fill="#FF9500" opacity="0.9"/>
+  <text x="50" y="68" text-anchor="middle" font-size="3.5" fill="white" font-weight="bold">APORT</text>
+  <ellipse cx="26" cy="55" rx="6" ry="12" fill="#007AFF" opacity="0.95"/>
+  <ellipse cx="74" cy="55" rx="6" ry="12" fill="#007AFF" opacity="0.95"/>
+  <ellipse cx="42" cy="78" rx="7" ry="10" fill="#007AFF" opacity="0.95"/>
+  <ellipse cx="58" cy="78" rx="7" ry="10" fill="#007AFF" opacity="0.95"/>
+  <ellipse cx="42" cy="77" rx="5" ry="2" fill="#1D1D1F" opacity="0.3"/>
+  <ellipse cx="58" cy="77" rx="5" ry="2" fill="#1D1D1F" opacity="0.3"/>
+  <g>
+    <circle cx="50" cy="55" r="16" fill="#34C759" opacity="0.15"/>
+    <circle cx="50" cy="55" r="13" fill="none" stroke="#34C759" stroke-width="2.5" opacity="0.9"/>
+    <path d="M 42 55 L 48 61 L 60 48" fill="none" stroke="#34C759" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" opacity="0.9"/>
+  </g>
+</svg>