@aporthq/aport-agent-guardrails 1.0.19 → 1.0.21

package/bin/lib/runtime.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Runtime asset installation for local APort evaluation.
+# Installs a self-contained shell runtime under <config_dir>/aport/runtime
+# from the repo/npm package sources in bin/, external/, and src/.
+
+set -euo pipefail
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+MANIFEST_FILE="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)/runtime-manifest.txt"
+
+_runtime_copy_file() {
+    local runtime_dir="$1"
+    local rel_path="$2"
+    local src="$ROOT_DIR/$rel_path"
+    local dest="$runtime_dir/$rel_path"
+
+    if [[ ! -f "$src" ]]; then
+        log_error "Runtime source missing: $src"
+        exit 1
+    fi
+
+    mkdir -p "$(dirname "$dest")"
+    cp "$src" "$dest"
+    chmod +x "$dest" 2> /dev/null || true
+}
+
+_runtime_copy_tree() {
+    local runtime_dir="$1"
+    local rel_path="$2"
+    local src="$ROOT_DIR/$rel_path"
+    local dest="$runtime_dir/$rel_path"
+
+    if [[ ! -d "$src" ]]; then
+        log_error "Runtime source directory missing: $src"
+        exit 1
+    fi
+
+    rm -rf "$dest"
+    mkdir -p "$(dirname "$dest")"
+    cp -R "$src" "$dest"
+}
+
+install_runtime_tree() {
+    local config_dir="$1"
+    local runtime_dir="$config_dir/aport/runtime"
+    local kind=""
+    local rel_path=""
+
+    mkdir -p "$runtime_dir"
+
+    if [[ ! -f "$MANIFEST_FILE" ]]; then
+        log_error "Runtime manifest missing: $MANIFEST_FILE"
+        exit 1
+    fi
+
+    while read -r kind rel_path; do
+        [[ -z "$kind" ]] && continue
+        [[ "$kind" == \#* ]] && continue
+        case "$kind" in
+            file)
+                _runtime_copy_file "$runtime_dir" "$rel_path"
+                ;;
+            tree)
+                _runtime_copy_tree "$runtime_dir" "$rel_path"
+                ;;
+            mkdir)
+                mkdir -p "$runtime_dir/$rel_path"
+                ;;
+            *)
+                log_error "Unsupported runtime manifest entry: $kind $rel_path"
+                exit 1
+                ;;
+        esac
+    done < "$MANIFEST_FILE"
+
+    chmod -R u+rwX "$runtime_dir" 2> /dev/null || true
+}
+
+export -f install_runtime_tree

package/bin/lib/tool-mapping.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+_aport_tool_mapping_file() {
+    local lib_dir
+    lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
+
+    local candidates=(
+        "$lib_dir/../../python/aport_guardrails/core/tool-pack-mapping.json"
+        "$lib_dir/../python/aport_guardrails/core/tool-pack-mapping.json"
+        "$lib_dir/../../aport/runtime/python/aport_guardrails/core/tool-pack-mapping.json"
+    )
+
+    local candidate=""
+    for candidate in "${candidates[@]}"; do
+        if [[ -f "$candidate" ]]; then
+            printf '%s\n' "$candidate"
+            return 0
+        fi
+    done
+    return 1
+}
+
+resolve_policy_id_from_tool_name() {
+    local tool_name="${1:-}"
+    local mapping_file=""
+    local normalized=""
+    local policy_id=""
+
+    normalized="$(printf '%s' "$tool_name" | tr '[:upper:]' '[:lower:]')"
+    mapping_file="$(_aport_tool_mapping_file)" || return 1
+
+    policy_id="$(
+        jq -r --arg tool "$normalized" '
+            first(
+              .rules[]?
+              | select(
+                  (.prefixes // [] | any(. as $prefix | $tool | startswith($prefix)))
+                  or
+                  (.substrings // [] | any(. as $substring | $tool | contains($substring)))
+                )
+              | .pack
+            ) // empty
+        ' "$mapping_file"
+    )"
+
+    if [[ -n "$policy_id" && "$policy_id" != "null" ]]; then
+        printf '%s\n' "$policy_id"
+        return 0
+    fi
+
+    return 1
+}

package/bin/lib/validation.sh

@@ -58,9 +58,9 @@ validate_tool_name() {
     return 0
 }
 
-# Validate passport path is within allowed directories
-# Returns 0 if safe, 1 if potentially dangerous
-validate_passport_path() {
+# Validate explicit operator-provided passport paths.
+# Returns 0 if the path is hygienic, 1 if it contains dangerous constructs.
+validate_explicit_passport_path() {
     local path="$1"
 
     # Check for empty
@@ -68,11 +68,28 @@ validate_passport_path() {
         return 1
     fi
 
+    # Check for path traversal attempts
+    if echo "$path" | grep -qE '\.\./|/\.\./|/\.\.$'; then
+        return 1
+    fi
+
+    return 0
+}
+
+# Validate auto-discovered/default passport paths against trusted framework dirs.
+# Returns 0 if safe, 1 if potentially dangerous.
+validate_passport_path() {
+    local path="$1"
+
+    if ! validate_explicit_passport_path "$path"; then
+        return 1
+    fi
+
     # Expand to absolute path
     local abs_path
     abs_path=$(readlink -f "$path" 2> /dev/null || realpath "$path" 2> /dev/null || echo "$path")
 
-    # Allowed base directories for passport storage
+    # Allowed base directories for auto-discovery
     local allowed_bases=(
         "$HOME/.openclaw"
         "$HOME/.aport"
@@ -82,7 +99,6 @@ validate_passport_path() {
         "/tmp/aport-"
     )
 
-    # Check if path starts with any allowed base
     local is_allowed=false
     for base in "${allowed_bases[@]}"; do
         case "$abs_path" in
@@ -90,6 +106,10 @@ validate_passport_path() {
                 is_allowed=true
                 break
                 ;;
+            "/private$base"*)
+                is_allowed=true
+                break
+                ;;
         esac
     done
 
@@ -97,16 +117,6 @@ validate_passport_path() {
         return 1
     fi
 
-    # Check for path traversal attempts
-    if echo "$path" | grep -qE '\.\./|/\.\./|/\.\.$'; then
-        return 1
-    fi
-
-    # Check for null bytes
-    if echo "$path" | grep -qF $'\0'; then
-        return 1
-    fi
-
     return 0
 }
 

package/docs/FRAMEWORK_ROADMAP.md

@@ -9,7 +9,7 @@ Public developer view of supported frameworks and roadmap. Details per framework
 | **OpenClaw** | Shipped | Full: plugin, wizard, local/API | [openclaw.md](frameworks/openclaw.md) | `npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor**   | Shipped | Full: hooks installer + script | [cursor.md](frameworks/cursor.md) | `npx @aporthq/aport-agent-guardrails cursor` |
 | **LangChain / LangGraph** | Shipped | **Python only:** callback, `aport-langchain setup` | [langchain.md](frameworks/langchain.md) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |
-| **CrewAI**   | Shipped | **Python only:** hook, decorator, `aport-crewai setup` | [crewai.md](frameworks/crewai.md) | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
+| **CrewAI**   | Shipped | **Python:** released hook adapter by default; native provider mode when available | [crewai.md](frameworks/crewai.md) | `npx @aporthq/aport-agent-guardrails crewai` then `pip install aport-agent-guardrails-crewai` + `aport-crewai setup` |
 
 **Coming soon:** n8n — custom node and runtime in progress ([n8n.md](frameworks/n8n.md)). Not listed in CLI options until shipped.
 

package/docs/PROVIDER.md

@@ -0,0 +1,90 @@
+# OAPGuardrailProvider
+
+APort ships a generic `OAPGuardrailProvider` for both Python and TypeScript. It implements whatever `GuardrailProvider` interface the target framework defines, wraps the core `Evaluator`, and works with any framework — no framework-specific code.
+
+## Architecture
+
+```
+Framework defines interface          APort implements it
+────────────────────────             ───────────────────
+DeerFlow: GuardrailProvider    ←──   Python OAPGuardrailProvider
+OpenClaw: GuardrailProvider    ←──   TypeScript OAPGuardrailProvider
+Your framework: same shape     ←──   Same class, same language
+```
+
+One provider per language. The core evaluation logic (tool mapping, passport loading, local/API mode, audit logging) is shared.
+
+## Python
+
+**Package:** `aport-agent-guardrails` (pip/uv)
+
+```python
+from aport_guardrails.providers import OAPGuardrailProvider
+
+provider = OAPGuardrailProvider(framework="deerflow")
+result = provider.evaluate(request)   # sync
+result = await provider.aevaluate(request)  # async
+```
+
+**Supported frameworks:** DeerFlow, CrewAI builds with native provider support, and any Python framework with a `GuardrailProvider` protocol.
+
+**Config:** `~/.aport/<framework>/config.yaml` (created by `aport setup --framework <name>`)
+
+**DeerFlow config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: aport_guardrails.providers.generic:OAPGuardrailProvider
+```
+
+## TypeScript
+
+**Package:** `@aporthq/aport-agent-guardrails-core` (npm)
+
+```typescript
+import { OAPGuardrailProvider } from "@aporthq/aport-agent-guardrails-core";
+
+const provider = new OAPGuardrailProvider({ framework: "openclaw" });
+const decision = await provider.evaluate(request);  // async
+const decision = provider.evaluateSync(request);     // sync
+```
+
+**Supported frameworks:** OpenClaw, any TypeScript framework with a `GuardrailProvider` interface.
+
+**Config:** `~/.openclaw/aport/config.yaml` or `~/.aport/<framework>/config.yaml`
+
+**OpenClaw config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: "@aporthq/aport-agent-guardrails-core"
+    config:
+      framework: "openclaw"
+```
+
+## What the provider does
+
+1. **Receives** `{ toolName, toolInput }` from the framework
+2. **Maps** tool name → OAP policy pack ID (e.g. `exec` → `system.command.execute.v1`)
+3. **Loads** passport from local file or hosted agent ID
+4. **Evaluates** locally (bash script, zero network) or via API (hosted evaluator)
+5. **Returns** `{ allow, reasons, policyId }` to the framework
+
+## Evaluation modes
+
+| Mode | Network | Latency | Use case |
+|---|---|---|---|
+| **Local** (default) | None | ~300ms | Development, CI, air-gapped |
+| **API** | Yes | ~65ms | Production, signed decisions, centralized dashboards |
+
+## Adding a new framework
+
+1. Check if the framework has a `GuardrailProvider` interface (or equivalent hook)
+2. Use the existing Python or TypeScript `OAPGuardrailProvider` — it's framework-agnostic
+3. Point the framework config at the provider class/package
+4. Run `npx @aporthq/aport-agent-guardrails <framework>` to create a passport
+5. Add a doc at `docs/frameworks/<framework>.md`
+
+No new provider code needed. The same `OAPGuardrailProvider` works for any framework in the same language.

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.18 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.21 (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.
 
@@ -32,7 +32,7 @@ So: **root = CLI/setup**; **core = library**. We publish core so that (1) the ad
 ## 2. Tooling
 
 - **Changesets** (Node): fixed mode so all workspace packages are in one “fixed” group and get the same version on release.
-- **sync-version script**: after `changeset version`, copies the new version from root `package.json` into all Python `pyproject.toml` and `aport_guardrails/__init__.py`.
+- **sync-version script**: after `changeset version`, reads the canonical version from the fixed workspace group and propagates it to the root CLI package, Python packages, manifests, lockfiles, and release docs.
 
 ---
 
@@ -43,7 +43,7 @@ So: **root = CLI/setup**; **core = library**. We publish core so that (1) the ad
    ```bash
    npm run version
    ```  
-   This runs `changeset version` (updates all Node `package.json` and CHANGELOGs) then `node scripts/sync-version.mjs` (updates Python packages to the same version).
+   This runs `changeset version` for the fixed workspace group, then `node scripts/sync-version.mjs` to align the root CLI package, Python packages, lockfiles, manifests, and release docs to that same version.
 3. **Commit** the version bump and changelog updates (e.g. “chore(release): 1.3.0”).
 4. **Tag and push** — this triggers the release workflow and publishes both npm and PyPI:
    ```bash

package/docs/development/ERROR_CODES.md

@@ -516,10 +516,10 @@ sudo yum install jq
 **Resolution**:
 ```bash
 # Check passport exists
-ls -la ~/.openclaw/passport.json
+ls -la ~/.openclaw/aport/passport.json
 
-# Check guardrail script exists
-ls -la ~/.openclaw/.skills/aport-guardrail.sh
+# Check local runtime exists
+ls -la ~/.openclaw/aport/runtime/bin/aport-guardrail.sh
 
 # Run setup if missing
 npx @aporthq/aport-agent-guardrails openclaw

package/docs/frameworks/crewai.md

@@ -1,51 +1,55 @@
-# APort Agent Guardrail — CrewAI
+# APort Agent Guardrails — CrewAI
 
-CrewAI supports **tool call hooks** that run before (and after) every tool execution. The **APort Agent Guardrail for CrewAI** plugs into the **before tool call** hook: we verify the tool and parameters against your passport and policy; if the decision is deny, we return `False` and CrewAI blocks execution. This matches CrewAI’s [Tool Call Hooks](https://docs.crewai.com/en/learn/tool-hooks) model.
+APort supports CrewAI in two ways:
 
-## How CrewAI agent guardrails work
+1. **Released CrewAI compatibility mode** via the existing `before_tool_call` adapter
+2. **Native provider mode** for CrewAI builds that expose a native guardrail provider seam
 
-- **Hooks:** CrewAI runs **before_tool_call** hooks before every tool execution. The hook receives a `ToolCallHookContext` (tool name, tool input, agent, task, crew). Returning `False` blocks execution; `True` or `None` allows it.
-- **Registration:** You can register a hook **globally** with `register_before_tool_call_hook()`, or use the `@before_tool_call` decorator, or use **crew-scoped** `@before_tool_call_crew` on a `@CrewBase` class.
-- **Multi-task crews:** The same hook runs for every tool call across all tasks and agents, so multi-task crews are supported by default.
+The default bootstrap path targets released CrewAI so it works today without waiting
+for upstream provider support.
 
-Our adapter provides a function that fits this API: it calls the APort evaluator (sync) and returns `False` on deny, `None` on allow. You register it once before running your crew.
+## Option 1: Released CrewAI Compatibility Mode
 
-- **Integration:** CrewAI `before_tool_call` hook (global or crew-scoped)
-- **Config:** `~/.aport/crewai/config.yaml` or `.aport/config.yaml` (see [Verification methods](../VERIFICATION_METHODS.md))
+This is the default mode.
 
-## Two ways to use APort
+Bootstrap config, passport, and local runtime with the Python-native CLI:
 
-| Use case | What it is | When to use it |
-|----------|------------|----------------|
-| **Guardrails (CLI/setup)** | One-line installer: runs the **passport wizard**, writes config, prints next steps. Does not run your app. | Getting started: create passport and config so the library can find them. |
-| **Core (library)** | The **evaluator** and **before-tool-call hook** in your code. Calls policy + passport to allow/deny each tool call. | Integrating into your app: register the hook so CrewAI blocks tool runs when policy denies. |
-
-You typically use **both**: run the CLI once to create passport and config, then use the library in your CrewAI app so every tool call is verified.
+```bash
+uvx --from aport-agent-guardrails aport setup --framework=crewai
+```
 
----
+Or use the Node bootstrap if you prefer:
 
-## Setup (Guardrails — create passport and config)
+```bash
+npx -y @aporthq/aport-agent-guardrails crewai
+```
 
-**Python**
+For CI or other non-interactive environments with the Python-native CLI:
 
 ```bash
-npx @aporthq/aport-agent-guardrails crewai   # wizard + config (optional)
-pip install aport-agent-guardrails-crewai
-aport-crewai setup
+APORT_CREWAI_CONFIG_DIR=.aport/crewai \
+uvx --from aport-agent-guardrails aport setup \
+  --framework=crewai \
+  --ci
 ```
 
-**Node**
+The equivalent Node bootstrap is:
 
 ```bash
-npx @aporthq/aport-agent-guardrails crewai   # wizard + config
-npm install @aporthq/aport-agent-guardrails-crewai   # beforeToolCall, withAPortGuardrail (depends on -core)
+APORT_CREWAI_CONFIG_DIR=.aport/crewai \
+npx -y @aporthq/aport-agent-guardrails crewai \
+  --output .aport/crewai/aport/passport.json \
+  --non-interactive
 ```
 
-`aport-crewai setup` (Python) writes config to `~/.aport/crewai/`, runs the passport wizard (or use `--ci` / `--no-wizard` for non-interactive), and prints next steps.
+Install the released CrewAI adapter:
 
-## Using the library (Core) in your app
+```bash
+pip install aport-agent-guardrails-crewai
+aport-crewai setup
+```
 
-**Python — Option 1: Register the hook before kickoff**
+Register the hook before your crew runs:
 
 ```python
 from aport_guardrails_crewai import register_aport_guardrail
@@ -54,66 +58,96 @@ register_aport_guardrail()
 crew.kickoff()
 ```
 
-**Python — Option 2: Decorator on your entry point**
+This path works with released CrewAI because it plugs directly into CrewAI's existing
+`before_tool_call` hook behavior.
 
-```python
-from aport_guardrails_crewai import with_aport_guardrail
+## Option 2: Native Provider Mode
 
-@with_aport_guardrail
-def main():
-    crew.kickoff()
+Use this only with a CrewAI build that exposes the native guardrail provider API.
 
-main()
+Bootstrap with native-mode instructions using the Python-native CLI:
+
+```bash
+uvx --from aport-agent-guardrails aport setup \
+  --framework=crewai \
+  --integration-mode=native
 ```
 
-**Python — Option 3: Use the hook with `@before_tool_call`**
+The equivalent Node bootstrap is:
 
-```python
-from crewai.hooks import before_tool_call
-from aport_guardrails_crewai import aport_guardrail_before_tool_call
+```bash
+npx -y @aporthq/aport-agent-guardrails crewai --integration-mode=native
+```
 
-@before_tool_call
-def my_guardrail(context):
-    return aport_guardrail_before_tool_call(context)
+Install the Python runtime package:
+
+```bash
+uv add aport-agent-guardrails
 ```
 
-**Node:** Call `beforeToolCall` in your flow before each tool run (CrewAI Node SDK does not expose a global hook). Return `false` to block, `null` to allow. Or wrap your entry point with `withAPortGuardrail(fn)`.
+Enable the provider before your crew runs:
 
-```ts
-import { beforeToolCall, withAPortGuardrail } from '@aporthq/aport-agent-guardrails-crewai';
+```python
+from crewai.hooks import enable_guardrail
+from aport_guardrails.providers import OAPGuardrailProvider
 
-// In your tool-call flow, before executing a tool:
-const result = beforeToolCall({ tool_name: 'run_command', tool_input: { command: 'ls' } });
-if (result === false) {
-  // Block this tool call
-  return;
-}
+enable_guardrail(
+    OAPGuardrailProvider(
+        framework="crewai",
+        config_path="~/.aport/crewai/config.yaml",
+    ),
+    fail_closed=True,
+)
 
-// Or wrap your crew kickoff so guardrail is in scope:
-withAPortGuardrail(() => {
-  crew.kickoff();
-});
+crew.kickoff()
 ```
 
-### How tool parameters are handled
+If you bootstrap into a project-local config directory, point `config_path` at that
+file instead.
+
+## What The Bootstrap Installs
 
-The Node middleware automatically spreads object tool inputs into the verification context. For example, `{ tool_input: { file_path: "/tmp/data.txt" } }` will pass `file_path` at the top level of the context, ensuring policies like `data.file.read.v1` receive required fields for validation.
+Both modes write:
 
-## Config
+- `~/.aport/crewai/config.yaml`
+- `~/.aport/crewai/aport/passport.json`
+- `~/.aport/crewai/aport/runtime/...`
 
-- **Config path:** `~/.aport/crewai/config.yaml`, or `.aport/config.yaml` in the project root.
-- **Mode:** `api` (default for production) or `local` (bash evaluator, no network). Same options as [LangChain](langchain.md) and OpenClaw.
-- **`fail_open_on_api_error`**: Set to `true` in config to allow tool execution when the APort API is unreachable (genuine policy denials are never overridden). Default: `false` (fail-closed).
+The compatibility and native modes share the same APort config and local runtime.
+Only the CrewAI integration layer changes.
 
-## Suspend (kill switch)
+## How APort Fits
 
-Same as all frameworks: **passport is the source of truth**. Local: set passport `status` to `suspended` (or `active` to resume). API: suspend the passport in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+- **Compatibility mode:** APort adapts to CrewAI's existing hook surface.
+- **Native mode:** CrewAI defines the seam, and APort plugs in as an external
+  `OAPGuardrailProvider`.
 
-## Example and tests
+That keeps CrewAI vendor-neutral while letting Open Agent Passport remain the
+portable policy/passport format across frameworks.
 
-- **Example:** [examples/crewai/run_with_guardrail.py](../../examples/crewai/run_with_guardrail.py) — temp config, ALLOW then DENY, `register_aport_guardrail()`.
-- **Unit tests:** [python/crewai_adapter/tests/test_hook.py](../../python/crewai_adapter/tests/test_hook.py) — hook return value and context with mocked evaluator.
+## Configuration
 
-## Status
+The provider and adapter read the standard APort config:
+
+- `mode: local` for the local shell evaluator
+- `mode: api` for hosted evaluation
+- `agent_id` for hosted passports
+- `passport_path` for explicit local passport paths
+- `guardrail_script` to override the local evaluator script path
+- `audit_log` to enable or disable audit logging
+
+With the default bootstrap, you usually do not need to set `guardrail_script`
+manually because the local runtime is installed under the framework config
+directory.
+
+## Validation
+
+After bootstrap, you can smoke-test the local evaluator directly:
+
+```bash
+~/.aport/crewai/aport/runtime/bin/aport-guardrail.sh \
+  system.command.execute \
+  '{"command":"git status"}'
+```
 
-Implemented (Story D). **APort Agent Guardrail for CrewAI.** Package: `aport-agent-guardrails-crewai`; CLI: `aport-crewai setup`; hook: `aport_guardrail_before_tool_call` / `register_aport_guardrail` / `with_aport_guardrail`.
+Exit code `0` means allow. Exit code `1` means deny.

package/docs/frameworks/deerflow.md

@@ -107,7 +107,7 @@ guardrails:
 | `bash`, `write_file`, `str_replace` | `system.command.execute.v1` |
 | `web_search`, `web_fetch`, `image_search` | `web.fetch.v1` |
 | `read_file`, `ls` | `data.file.read.v1` |
-| `present_file`, `view_image` | `data.export.create.v1` |
+| `present_file`, `view_image` | `data.file.read.v1` |
 | `ask_clarification`, `task` | `agent.session.create.v1` |
 | MCP tools (dynamic) | `mcp.tool.execute.v1` |