@aporthq/aport-agent-guardrails 1.0.8

package/bin/aport-status.sh

@@ -0,0 +1,276 @@
+#!/bin/bash
+# aport-status.sh
+# Display APort passport status and recent activity
+#
+# Usage: ./aport-status.sh [--passport FILE]
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=bin/aport-resolve-paths.sh
+. "${SCRIPT_DIR}/bin/aport-resolve-paths.sh"
+
+if [ "$1" = "--passport" ] && [ -n "$2" ]; then
+    PASSPORT_FILE="$2"
+fi
+
+echo "🛂 APort Status Dashboard"
+echo "========================="
+echo
+
+# Passport info (passport status is source of truth for suspend; no separate kill-switch file)
+if [ ! -f "$PASSPORT_FILE" ]; then
+    echo "❌ Passport: NOT FOUND"
+    echo "   Location: $PASSPORT_FILE"
+    echo "   Create one with: aport-create-passport.sh"
+    echo
+    exit 1
+fi
+
+echo "📋 Passport Information"
+echo "   Location: $PASSPORT_FILE"
+
+# Check jq availability
+if ! command -v jq &> /dev/null; then
+    echo "   ⚠️  jq not found - install with: brew install jq"
+    echo
+    exit 1
+fi
+
+echo "   ID: $(jq -r '.passport_id // "unknown"' $PASSPORT_FILE)"
+echo "   Kind: $(jq -r '.kind // "unknown"' $PASSPORT_FILE)"
+echo "   Owner: $(jq -r '.owner_id // "unknown"' $PASSPORT_FILE) ($(jq -r '.owner_type // "unknown"' $PASSPORT_FILE))"
+echo "   Spec Version: $(jq -r '.spec_version // "unknown"' $PASSPORT_FILE)"
+echo "   Assurance Level: $(jq -r '.assurance_level // "unknown"' $PASSPORT_FILE)"
+
+# Status with color
+status=$(jq -r '.status // "unknown"' $PASSPORT_FILE)
+if [ "$status" = "active" ]; then
+    echo "   Status: ✅ active"
+elif [ "$status" = "suspended" ]; then
+    echo "   Status: 🔴 suspended"
+elif [ "$status" = "revoked" ]; then
+    echo "   Status: ❌ revoked"
+else
+    echo "   Status: ⚠️  $status"
+fi
+
+# Display agent metadata if available
+agent_name=$(jq -r '.metadata.name // ""' $PASSPORT_FILE)
+if [ -n "$agent_name" ] && [ "$agent_name" != "null" ]; then
+    echo "   Agent Name: $agent_name"
+fi
+
+# Expiration with warning
+never_expires=$(jq -r '.never_expires // "false"' $PASSPORT_FILE)
+expires_at=$(jq -r '.expires_at // "null"' $PASSPORT_FILE)
+
+if [ "$never_expires" = "true" ]; then
+    echo "   Expires: Never"
+elif [ "$expires_at" != "null" ] && [ "$expires_at" != "unknown" ]; then
+    echo "   Expires: $expires_at"
+
+    # Calculate days until expiration
+    if date -v+1d &> /dev/null 2>&1; then
+        # BSD date (macOS)
+        expires_ts=$(date -jf "%Y-%m-%dT%H:%M:%SZ" "$expires_at" +%s 2> /dev/null || echo 0)
+    else
+        # GNU date (Linux)
+        expires_ts=$(date -d "$expires_at" +%s 2> /dev/null || echo 0)
+    fi
+
+    now_ts=$(date +%s)
+    days_left=$((($expires_ts - $now_ts) / 86400))
+
+    if [ $days_left -le 0 ]; then
+        echo "   ⚠️  EXPIRED $((days_left * -1)) days ago"
+    elif [ $days_left -le 7 ]; then
+        echo "   ⚠️  Expires in $days_left days - renew soon!"
+    else
+        echo "   ✅ $days_left days until expiration"
+    fi
+else
+    echo "   Expires: Not set"
+fi
+
+echo
+
+# Capabilities
+echo "🔐 Capabilities"
+cap_count=$(jq '.capabilities | length' $PASSPORT_FILE)
+if [ "$cap_count" -eq 0 ]; then
+    echo "   (none configured)"
+else
+    jq -r '.capabilities[].id // empty' $PASSPORT_FILE | while read cap; do
+        echo "   • $cap"
+    done
+fi
+
+echo
+
+# Limits summary
+echo "⚙️  Limits"
+jq -r '.limits | keys[]? // empty' $PASSPORT_FILE | while read policy; do
+    echo "   • $policy:"
+    case "$policy" in
+        "code.repository.merge")
+            max_prs=$(jq -r ".limits.\"$policy\".max_prs_per_day // \"unlimited\"" $PASSPORT_FILE)
+            max_size=$(jq -r ".limits.\"$policy\".max_pr_size_kb // \"unlimited\"" $PASSPORT_FILE)
+            echo "     - Max PRs/day: $max_prs"
+            echo "     - Max PR size: $max_size files"
+            ;;
+        "system.command.execute")
+            max_time=$(jq -r ".limits.\"$policy\".max_execution_time // \"unlimited\"" $PASSPORT_FILE)
+            echo "     - Max execution time: $max_time seconds"
+            blocked_count=$(jq ".limits.\"$policy\".blocked_patterns | length" $PASSPORT_FILE)
+            echo "     - Blocked patterns: $blocked_count"
+            ;;
+        "messaging.message.send")
+            msgs_per_day=$(jq -r ".limits.\"$policy\".msgs_per_day // \"unlimited\"" $PASSPORT_FILE)
+            echo "     - Messages/day: $msgs_per_day"
+            ;;
+        "data.export")
+            max_rows=$(jq -r ".limits.\"$policy\".max_rows // \"unlimited\"" $PASSPORT_FILE)
+            allow_pii=$(jq -r ".limits.\"$policy\".allow_pii // false" $PASSPORT_FILE)
+            echo "     - Max rows: $max_rows"
+            echo "     - PII export: $allow_pii"
+            ;;
+    esac
+done
+
+echo
+
+# Latest decision (OAP v1.0 format)
+if [ -f "$DECISION_FILE" ]; then
+    echo "🔍 Latest Decision"
+    allow=$(jq -r '.allow // "unknown"' $DECISION_FILE)
+    decision_id=$(jq -r '.decision_id // "unknown"' $DECISION_FILE)
+    policy_id=$(jq -r '.policy_id // "unknown"' $DECISION_FILE)
+
+    if [ "$allow" = "true" ]; then
+        echo "   ✅ ALLOW"
+    else
+        echo "   ❌ DENY"
+    fi
+    echo "   Decision ID: $decision_id"
+    echo "   Policy ID: $policy_id"
+
+    # Display OAP v1.0 reasons array
+    reasons_count=$(jq '.reasons | length' $DECISION_FILE 2> /dev/null || echo 0)
+    if [ "$reasons_count" -gt 0 ]; then
+        echo "   Reasons:"
+        jq -r '.reasons[] | "     - [\(.code)] \(.message)"' $DECISION_FILE
+    fi
+
+    # Display issued_at and expires_at
+    issued_at=$(jq -r '.issued_at // "unknown"' $DECISION_FILE)
+    expires_at_decision=$(jq -r '.expires_at // "unknown"' $DECISION_FILE)
+    if [ "$issued_at" != "unknown" ]; then
+        echo "   Issued: $issued_at"
+    fi
+    if [ "$expires_at_decision" != "unknown" ]; then
+        echo "   Expires: $expires_at_decision"
+    fi
+
+    # Display signature info
+    kid=$(jq -r '.kid // "unknown"' $DECISION_FILE)
+    if [ "$kid" != "unknown" ]; then
+        echo "   Key ID: $kid"
+    fi
+    # Show capability context from last audit line (command, recipient, repo/branch)
+    if [ -f "$AUDIT_LOG" ] && [ -s "$AUDIT_LOG" ]; then
+        last_context=$(tail -1 "$AUDIT_LOG" | sed -n 's/.*context="\([^"]*\)".*/\1/p')
+        if [ -n "$last_context" ]; then
+            echo "   Context: $last_context"
+        fi
+    fi
+    echo
+fi
+
+# Recent activity
+echo "📊 Recent Activity (last 10)"
+if [ -f "$AUDIT_LOG" ] && [ -s "$AUDIT_LOG" ]; then
+    tail -10 "$AUDIT_LOG" | while IFS= read -r line; do
+        # Parse log line: [timestamp] tool=X decision_id=Y allow=Z ... context="..." (optional)
+        timestamp=$(echo "$line" | sed -n 's/.*\[\([^]]*\)\].*/\1/p')
+        tool=$(echo "$line" | sed -n 's/.*tool=\([^ ]*\).*/\1/p')
+        allow=$(echo "$line" | sed -n 's/.*allow=\([^ ]*\).*/\1/p')
+        context=$(echo "$line" | sed -n 's/.*context="\([^"]*\)".*/\1/p')
+        timestamp=${timestamp:-unknown}
+        tool=${tool:-unknown}
+        allow=${allow:-unknown}
+
+        short_time=$(echo "$timestamp" | cut -d' ' -f1-2 | cut -d'.' -f1)
+        # Show capability + context when present (e.g. "exec.run | cat test.md"); truncate long context
+        if [ -n "$context" ]; then
+            context_show=$(printf '%.80s' "$context")
+            [ "${#context}" -gt 80 ] && context_show="${context_show}..."
+            detail="$tool | $context_show"
+        else
+            detail="$tool"
+        fi
+
+        if [ "$allow" = "true" ]; then
+            printf "   ✅ %s | %s\n" "$short_time" "$detail"
+        else
+            printf "   ❌ %s | %s\n" "$short_time" "$detail"
+        fi
+    done
+else
+    echo "   (no activity yet)"
+fi
+
+echo
+
+# Usage statistics (sanitize numbers for macOS/BSD)
+if [ -f "$AUDIT_LOG" ] && [ -s "$AUDIT_LOG" ]; then
+    echo "📈 Statistics (all time)"
+    total_actions=$(wc -l < "$AUDIT_LOG" | tr -d '[:space:]')
+    total_actions=${total_actions:-0}
+    allowed=$(grep -c "allow=true" "$AUDIT_LOG" 2> /dev/null || true)
+    allowed=$(echo "$allowed" | tr -d '[:space:]')
+    allowed=${allowed:-0}
+    denied=$(grep -c "allow=false" "$AUDIT_LOG" 2> /dev/null || true)
+    denied=$(echo "$denied" | tr -d '[:space:]')
+    denied=${denied:-0}
+
+    echo "   Total actions: $total_actions"
+    echo "   Allowed: $allowed"
+    echo "   Denied: $denied"
+
+    if [ -n "$total_actions" ] && [ "$total_actions" -gt 0 ] 2> /dev/null; then
+        allow_pct=$((100 * allowed / total_actions))
+        echo "   Allow rate: ${allow_pct}%"
+    fi
+    echo
+fi
+
+# Commands
+echo "💡 Useful Commands"
+echo "   • View full audit log: tail -f $AUDIT_LOG"
+echo "   • Edit passport: vim $PASSPORT_FILE"
+echo "   • Test policy: aport-guardrail.sh <tool_name> '<context_json>'"
+echo "   • Suspend agent (local): set passport status to \"suspended\" in $PASSPORT_FILE (edit with jq or editor)"
+echo "   • Resume: set status back to \"active\""
+echo
+
+# Upgrade hint (show once per day)
+HINT_FILE="$HOME/.openclaw/.last-status-upgrade-hint"
+if [ ! -f "$HINT_FILE" ] || [ $(($(date +%s) - $(stat -f %m "$HINT_FILE" 2> /dev/null || stat -c %Y "$HINT_FILE" 2> /dev/null || echo 0))) -gt 86400 ]; then
+    echo "💰 Upgrade to APort Cloud?"
+    echo "   You're using APort Local (free tier) - perfect for individual developers!"
+    echo
+    echo "   Upgrade to APort Cloud for teams:"
+    echo "   • Multi-machine sync (passport changes propagate <15s)"
+    echo "   • Global suspend (remote passports): log in at aport.io and suspend passport; all agents using it deny in <30s"
+    echo "   • Ed25519 signed audit logs (court-admissible, SOC 2/IIROC compliant)"
+    echo "   • Team collaboration (shared passports, role-based policies)"
+    echo "   • Analytics dashboard (usage metrics, risk scoring, anomaly detection)"
+    echo
+    echo "   Pricing: \$99/user/month (Pro) | \$149/user/month (Enterprise)"
+    echo "   Free trial: https://aport.io/trial"
+    echo "   Learn more: https://aport.io/upgrade"
+    echo
+
+    touch "$HINT_FILE"
+fi

package/bin/frameworks/crewai.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# CrewAI framework installer/setup
+# Config: ~/.aport/crewai/ or .aport/config.yaml
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+# shellcheck source=../lib/common.sh
+source "$LIB/common.sh"
+# shellcheck source=../lib/passport.sh
+source "$LIB/passport.sh"
+# shellcheck source=../lib/config.sh
+source "$LIB/config.sh"
+
+run_setup() {
+    log_info "Setting up APort guardrails for CrewAI..."
+    config_dir="$(write_config_template crewai)"
+    mkdir -p "$config_dir/aport"
+    export APORT_FRAMEWORK=crewai
+    run_passport_wizard "$@"
+    echo ""
+    echo "  Next steps (CrewAI):"
+    echo "  ───────────────────"
+    echo "  1. Install the Python adapter (required for runtime enforcement):"
+    echo "     pip install aport-agent-guardrails-crewai"
+    echo "     aport-crewai setup"
+    echo "  2. Config written to: $config_dir"
+    echo "  3. Register the guardrail before running your crew:"
+    echo ""
+    echo "     from aport_guardrails_crewai import register_aport_guardrail"
+    echo "     register_aport_guardrail()"
+    echo "     crew.kickoff()"
+    echo ""
+    echo "  Or: @with_aport_guardrail on your entry point. See: docs/frameworks/crewai.md"
+    echo ""
+    # Fail loudly if Python available but adapter not installed (Issue 4); skip in CI/tests
+    if [[ -z "${APORT_SKIP_ADAPTER_CHECK:-}" ]]; then
+        if command -v pip &> /dev/null || command -v pip3 &> /dev/null; then
+            pip_cmd="pip"
+            command -v pip3 &> /dev/null && pip_cmd="pip3"
+            if ! $pip_cmd show aport-agent-guardrails-crewai &> /dev/null; then
+                echo "[aport] ERROR: Python adapter not installed. Run the following, then use your agent:" >&2
+                echo "  $pip_cmd install aport-agent-guardrails-crewai" >&2
+                echo "  aport-crewai setup" >&2
+                exit 1
+            fi
+        fi
+    fi
+}
+
+run_setup "$@"

package/bin/frameworks/cursor.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Cursor (and optional Copilot/Claude Code) framework installer/setup.
+# Runs passport wizard and writes ~/.cursor/hooks.json pointing at the APort hook script.
+# Same hook script works for Cursor, VS Code + Copilot, and Claude Code.
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+# shellcheck source=../lib/common.sh
+source "$LIB/common.sh"
+# shellcheck source=../lib/passport.sh
+source "$LIB/passport.sh"
+# shellcheck source=../lib/config.sh
+source "$LIB/config.sh"
+
+run_setup() {
+    log_info "Setting up APort guardrails for Cursor..."
+    # Passport and data live under Cursor's config dir (~/.cursor/aport/ by default).
+    config_dir="$(get_config_dir cursor)"
+    mkdir -p "$config_dir/aport"
+
+    export APORT_FRAMEWORK=cursor
+    run_passport_wizard "$@"
+
+    # Resolve absolute path to hook script (works from repo or npx package)
+    HOOK_SCRIPT="${APORT_CURSOR_HOOK_SCRIPT:-}"
+    if [ -z "$HOOK_SCRIPT" ]; then
+        ROOT_FOR_HOOK="$(cd "$LIB/../.." && pwd)"
+        HOOK_SCRIPT="$ROOT_FOR_HOOK/bin/aport-cursor-hook.sh"
+    fi
+    if [ ! -f "$HOOK_SCRIPT" ]; then
+        log_warn "Hook script not found at $HOOK_SCRIPT; hooks.json will reference it (create the file for hooks to work)."
+    else
+        HOOK_SCRIPT="$(cd "$(dirname "$HOOK_SCRIPT")" && pwd)/$(basename "$HOOK_SCRIPT")"
+    fi
+
+    # Write Cursor hooks config: beforeShellExecution and preToolUse run the same script
+    CURSOR_HOOKS_DIR="${CURSOR_HOOKS_DIR:-$HOME/.cursor}"
+    CURSOR_HOOKS_FILE="$CURSOR_HOOKS_DIR/hooks.json"
+    mkdir -p "$CURSOR_HOOKS_DIR"
+
+    # Merge with existing hooks.json if present; otherwise create new
+    if [ -f "$CURSOR_HOOKS_FILE" ] && command -v jq &> /dev/null; then
+        EXISTING=$(cat "$CURSOR_HOOKS_FILE")
+        if echo "$EXISTING" | jq -e '.hooks' &> /dev/null; then
+            # Add APort hook to beforeShellExecution and preToolUse (avoid duplicate)
+            NEW_HOOKS=$(echo "$EXISTING" | jq -c --arg cmd "$HOOK_SCRIPT" '
+        (.hooks.beforeShellExecution // []) as $b |
+        (.hooks.preToolUse // []) as $p |
+        .hooks.beforeShellExecution = ($b | map(select(.command != $cmd)) | . + [{ "command": $cmd }]) |
+        .hooks.preToolUse = ($p | map(select(.command != $cmd)) | . + [{ "command": $cmd }])
+      ')
+            echo "$NEW_HOOKS" > "$CURSOR_HOOKS_FILE"
+        else
+            _write_cursor_hooks_file "$CURSOR_HOOKS_FILE" "$HOOK_SCRIPT"
+        fi
+    else
+        _write_cursor_hooks_file "$CURSOR_HOOKS_FILE" "$HOOK_SCRIPT"
+    fi
+
+    echo ""
+    echo "  Next steps (Cursor):"
+    echo "  ────────────────────"
+    echo "  1. Hooks config written to: $CURSOR_HOOKS_FILE"
+    echo "  2. Hook script: $HOOK_SCRIPT"
+    echo "  3. Restart Cursor (or reload window) so hooks are picked up."
+    echo "  4. Shell commands and tool use will be checked by APort policy (exit 2 = block)."
+    echo ""
+    echo "  Same script works for VS Code + Copilot and Claude Code — see: docs/frameworks/cursor.md"
+    echo ""
+}
+
+_write_cursor_hooks_file() {
+    local file="$1"
+    local cmd="$2"
+    if command -v jq &> /dev/null; then
+        jq -n -c --arg cmd "$cmd" '{
+      version: 1,
+      hooks: {
+        beforeShellExecution: [{ command: $cmd }],
+        preToolUse: [{ command: $cmd }]
+      }
+    }' > "$file"
+    else
+        cat > "$file" << EOF
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [{"command": "$cmd"}],
+    "preToolUse": [{"command": "$cmd"}]
+  }
+}
+EOF
+    fi
+}
+
+run_setup "$@"

package/bin/frameworks/langchain.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# LangChain/LangGraph framework installer/setup
+# Config: ~/.aport/langchain/ or .aport/config.yaml
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+# shellcheck source=../lib/common.sh
+source "$LIB/common.sh"
+# shellcheck source=../lib/passport.sh
+source "$LIB/passport.sh"
+# shellcheck source=../lib/config.sh
+source "$LIB/config.sh"
+
+run_setup() {
+    log_info "Setting up APort guardrails for LangChain..."
+    config_dir="$(write_config_template langchain)"
+    mkdir -p "$config_dir/aport"
+    export APORT_FRAMEWORK=langchain
+    run_passport_wizard "$@"
+    echo ""
+    echo "  Next steps (LangChain):"
+    echo "  ───────────────────────"
+    echo "  1. Install the Python adapter (required for runtime enforcement):"
+    echo "     pip install aport-agent-guardrails-langchain"
+    echo "     aport-langchain setup"
+    echo "  2. Config written to: $config_dir"
+    echo "  3. Add to your agent:"
+    echo ""
+    echo "     from aport_guardrails_langchain import APortCallback"
+    echo "     agent = initialize_agent(..., callbacks=[APortCallback()])"
+    echo ""
+    echo "  See: docs/frameworks/langchain.md"
+    echo ""
+    # Fail loudly if Python available but adapter not installed (Issue 4); skip in CI/tests
+    if [[ -z "${APORT_SKIP_ADAPTER_CHECK:-}" ]]; then
+        if command -v pip &> /dev/null || command -v pip3 &> /dev/null; then
+            pip_cmd="pip"
+            command -v pip3 &> /dev/null && pip_cmd="pip3"
+            if ! $pip_cmd show aport-agent-guardrails-langchain &> /dev/null; then
+                echo "[aport] ERROR: Python adapter not installed. Run the following, then use your agent:" >&2
+                echo "  $pip_cmd install aport-agent-guardrails-langchain" >&2
+                echo "  aport-langchain setup" >&2
+                exit 1
+            fi
+        fi
+    fi
+}
+
+run_setup "$@"

package/bin/frameworks/n8n.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# n8n framework installer/setup
+# Custom node + credentials; config in n8n credentials store.
+#
+# ⚠️  n8n custom node is NOT YET AVAILABLE. This script only runs the passport wizard
+#     and writes config. No APort node is installed. See docs/frameworks/n8n.md and
+#     DEPLOYMENT_READINESS.md for status.
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+# shellcheck source=../lib/common.sh
+source "$LIB/common.sh"
+# shellcheck source=../lib/passport.sh
+source "$LIB/passport.sh"
+# shellcheck source=../lib/config.sh
+source "$LIB/config.sh"
+
+run_setup() {
+    echo "  APort n8n support: coming soon. This installer writes config only; custom node not yet available."
+    echo ""
+    log_info "Setting up APort guardrails for n8n..."
+    config_dir="$(write_config_template n8n)"
+    mkdir -p "$config_dir/aport"
+    export APORT_FRAMEWORK=n8n
+    run_passport_wizard "$@"
+    echo ""
+    echo "  Next steps (n8n):"
+    echo "  ────────────────"
+    echo "  1. Install custom node to ~/.n8n/custom/ (or use HTTP Request node to APort API)."
+    echo "  2. In your workflow: add APort Guardrail node before action nodes; branch on allow/deny."
+    echo "  3. Store agent_id or passport in n8n credentials."
+    echo ""
+    echo "  See: docs/frameworks/n8n.md"
+    echo ""
+}
+
+run_setup "$@"

package/bin/frameworks/openclaw.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# OpenClaw framework: delegate to full installer so passport wizard, config,
+# plugin, and next steps all run identically (single source of truth in bin/openclaw).
+# Pass-through: all arguments ($@) are passed to bin/openclaw (e.g. agent_id for
+# hosted passport, or any future flags/openclaw options). Non-interactive use
+# (e.g. agent_id only) is unchanged when invoked via agent-guardrails openclaw <agent_id>.
+
+# shellcheck source=../lib/common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/../lib/common.sh"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
+OPENCLAW_BIN="$SCRIPT_DIR/../openclaw"
+
+if [[ ! -x "$OPENCLAW_BIN" ]]; then
+    log_error "OpenClaw installer not found: $OPENCLAW_BIN"
+    exit 1
+fi
+
+exec "$OPENCLAW_BIN" "$@"

package/bin/lib/allowlist.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Command allowlisting helpers (shared across frameworks)
+# Used by evaluator / policy to check allowed_commands vs blocked patterns.
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+# Placeholder: allowlist check logic can be shared between bash evaluator and API
+# Returns 0 if command is allowed, 1 if denied
+check_command_allowed() {
+    local command_line="$1"
+    local allowed_list="${2:-*}"
+    # TODO: Implement against passport allowed_commands + blocked patterns
+    [[ -z "$command_line" ]] && return 1
+    return 0
+}
+
+export -f check_command_allowed

package/bin/lib/common.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Shared bash functions for APort agent-guardrails (multi-framework)
+# Used by passport wizard, config helpers, and framework installers.
+
+set -euo pipefail
+
+# Resolve script directory and project root
+SCRIPT_DIR="${SCRIPT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)}"
+# Project root: bin/lib -> repo root
+ROOT_DIR="${ROOT_DIR:-$(cd "$SCRIPT_DIR/../.." 2> /dev/null && pwd)}"
+
+# Log helpers
+log_info() { echo "[aport] $*" >&2; }
+log_warn() { echo "[aport] WARN: $*" >&2; }
+log_error() { echo "[aport] ERROR: $*" >&2; }
+
+# Check required commands
+require_cmd() {
+    local cmd="$1"
+    if ! command -v "$cmd" &> /dev/null; then
+        log_error "Required command not found: $cmd"
+        exit 1
+    fi
+}
+
+# Export for subshells
+export SCRIPT_DIR ROOT_DIR
+export -f log_info log_warn log_error require_cmd

package/bin/lib/config.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Config file management (shared across frameworks)
+# Read/write config, env vars, credential paths.
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+# Default config locations per framework (where that framework stores data; can be overridden by env).
+# Default passport path = get_config_dir/aport/passport.json. Keep in sync with packages/core default-passport-paths.json.
+get_config_dir() {
+    local framework="${1:-}"
+    case "$framework" in
+        openclaw) echo "${APORT_OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" ;;
+        langchain) echo "${APORT_LANGCHAIN_CONFIG_DIR:-$HOME/.aport/langchain}" ;;
+        crewai) echo "${APORT_CREWAI_CONFIG_DIR:-$HOME/.aport/crewai}" ;;
+        n8n) echo "${APORT_N8N_CONFIG_DIR:-$HOME/.n8n}" ;;
+        cursor) echo "${APORT_CURSOR_CONFIG_DIR:-$HOME/.cursor}" ;;
+        *) echo "${APORT_CONFIG_DIR:-$HOME/.aport}" ;;
+    esac
+}
+
+# Default passport path per framework (config_dir/aport/passport.json). Used by wizard and evaluator.
+get_default_passport_path() {
+    local framework="${1:-}"
+    local config_dir
+    config_dir="$(get_config_dir "$framework")"
+    config_dir="${config_dir/#\~/$HOME}"
+    echo "${config_dir}/aport/passport.json"
+}
+
+write_config_template() {
+    local framework="$1"
+    local dest_dir
+    dest_dir="$(get_config_dir "$framework")"
+    mkdir -p "$dest_dir"
+    log_info "Config directory: $dest_dir"
+    local lib_dir templates_dir
+    lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")" && pwd)"
+    templates_dir="$lib_dir/templates"
+    if [[ -f "$templates_dir/config.yaml" ]]; then
+        cp "$templates_dir/config.yaml" "$dest_dir/config.yaml" 2> /dev/null || true
+    fi
+    echo "$dest_dir"
+}
+
+export -f get_config_dir get_default_passport_path write_config_template