@aporthq/aport-agent-guardrails 1.0.8

package/bin/lib/constants.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# constants.sh - Configuration constants and defaults for APort guardrails
+# All magic numbers and hardcoded values should be defined here
+
+# ============================================================================
+# TIMEOUTS (seconds)
+# ============================================================================
+
+# Default timeout for subprocess guardrail script execution
+readonly DEFAULT_SUBPROCESS_TIMEOUT="${APORT_SUBPROCESS_TIMEOUT:-30}"
+
+# Default timeout for API requests
+readonly DEFAULT_API_TIMEOUT="${APORT_API_TIMEOUT:-15}"
+
+# Timeout for loading policy packs
+readonly DEFAULT_POLICY_LOAD_TIMEOUT="${APORT_POLICY_LOAD_TIMEOUT:-5}"
+
+# ============================================================================
+# SIZE LIMITS
+# ============================================================================
+
+# Maximum tool name length (characters)
+readonly MAX_TOOL_NAME_LENGTH="${APORT_MAX_TOOL_NAME_LENGTH:-128}"
+
+# Maximum agent ID length (characters)
+readonly MAX_AGENT_ID_LENGTH="${APORT_MAX_AGENT_ID_LENGTH:-128}"
+
+# Maximum policy pack ID length (characters)
+readonly MAX_POLICY_PACK_ID_LENGTH="${APORT_MAX_POLICY_PACK_ID_LENGTH:-128}"
+
+# Maximum context JSON size (bytes) - default 100KB
+readonly MAX_CONTEXT_SIZE_BYTES="${APORT_MAX_CONTEXT_SIZE:-102400}"
+
+# Maximum passport file size (bytes) - default 1MB
+readonly MAX_PASSPORT_SIZE_BYTES="${APORT_MAX_PASSPORT_SIZE:-1048576}"
+
+# Maximum policy pack file size (bytes) - default 10MB
+readonly MAX_POLICY_PACK_SIZE_BYTES="${APORT_MAX_POLICY_PACK_SIZE:-10485760}"
+
+# Maximum log message length (characters)
+readonly MAX_LOG_MESSAGE_LENGTH="${APORT_MAX_LOG_MESSAGE_LENGTH:-200}"
+
+# ============================================================================
+# RATE LIMITING
+# ============================================================================
+
+# Default requests per minute
+readonly DEFAULT_RATE_LIMIT_RPM="${APORT_RATE_LIMIT_REQUESTS_PER_MINUTE:-60}"
+
+# Default burst allowance
+readonly DEFAULT_RATE_LIMIT_BURST="${APORT_RATE_LIMIT_BURST:-10}"
+
+# ============================================================================
+# RETRY LOGIC
+# ============================================================================
+
+# Maximum API retry attempts
+readonly MAX_API_RETRIES="${APORT_MAX_API_RETRIES:-3}"
+
+# API retry backoff (milliseconds)
+readonly API_RETRY_BACKOFF_MS="${APORT_API_RETRY_BACKOFF_MS:-1000}"
+
+# ============================================================================
+# CACHING
+# ============================================================================
+
+# Passport file cache TTL (seconds)
+readonly PASSPORT_CACHE_TTL_SECONDS="${APORT_PASSPORT_CACHE_TTL:-60}"
+
+# Policy pack cache TTL (seconds)
+readonly POLICY_CACHE_TTL_SECONDS="${APORT_POLICY_CACHE_TTL:-60}"
+
+# Config file cache TTL (seconds)
+readonly CONFIG_CACHE_TTL_SECONDS="${APORT_CONFIG_CACHE_TTL:-300}"
+
+# ============================================================================
+# API CONFIGURATION
+# ============================================================================
+
+# Default API URL
+readonly DEFAULT_API_URL="${APORT_API_URL:-https://api.aport.io}"
+
+# ============================================================================
+# PATHS
+# ============================================================================
+
+# Allowed base directories for passport files (for validation)
+readonly ALLOWED_PASSPORT_BASE_DIRS=(
+    "$HOME/.openclaw"
+    "$HOME/.aport"
+    "/tmp/aport-"
+)
+
+# ============================================================================
+# VALIDATION PATTERNS
+# ============================================================================
+
+# Tool name validation pattern (grep -E compatible)
+readonly TOOL_NAME_PATTERN='^[a-zA-Z0-9._-]+$'
+
+# Agent ID validation pattern (grep -E compatible)
+readonly AGENT_ID_PATTERN='^ap_[a-zA-Z0-9_]+$'
+
+# Policy pack ID validation pattern (grep -E compatible)
+readonly POLICY_PACK_ID_PATTERN='^[a-zA-Z0-9._-]+$'
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+# Log level (DEBUG, INFO, WARN, ERROR)
+readonly LOG_LEVEL="${APORT_LOG_LEVEL:-INFO}"
+
+# Log format (text, json)
+readonly LOG_FORMAT="${APORT_LOG_FORMAT:-text}"
+
+# ============================================================================
+# SECURITY
+# ============================================================================
+
+# Sensitive field patterns for log redaction (space-separated)
+readonly SENSITIVE_FIELD_PATTERNS="password passwd pwd secret token key api bearer"
+
+# API key prefix patterns (space-separated)
+readonly API_KEY_PREFIXES="aprt_ sk_ pk_"
+
+# ============================================================================
+# PERFORMANCE
+# ============================================================================
+
+# Slow operation threshold (milliseconds)
+readonly SLOW_OPERATION_THRESHOLD_MS="${APORT_SLOW_OPERATION_THRESHOLD_MS:-200}"
+
+# ============================================================================
+# FEATURE FLAGS
+# ============================================================================
+
+# Enable policy caching (1=enabled, 0=disabled)
+readonly ENABLE_POLICY_CACHING="${APORT_ENABLE_POLICY_CACHING:-1}"
+
+# Enable passport caching (1=enabled, 0=disabled)
+readonly ENABLE_PASSPORT_CACHING="${APORT_ENABLE_PASSPORT_CACHING:-1}"
+
+# ============================================================================
+# VERSION
+# ============================================================================
+
+# APort specification version
+readonly OAP_SPEC_VERSION="oap/1.0"
+
+# Client library version
+readonly CLIENT_VERSION="1.0.8"
+
+# ============================================================================
+# MISC
+# ============================================================================
+
+# Audit log file name
+readonly AUDIT_LOG_FILENAME="audit.log"
+
+# Chain state file name
+readonly CHAIN_STATE_FILENAME="chain-state.json"
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+# Get numeric constant with validation
+# Usage: get_numeric_constant "var_name" "default_value" "min" "max"
+get_numeric_constant() {
+    local var_name="$1"
+    local default_value="$2"
+    local min_value="${3:-1}"
+    local max_value="${4:-999999}"
+
+    local value="${!var_name:-$default_value}"
+
+    # Validate it's a number
+    if ! [[ "$value" =~ ^[0-9]+$ ]]; then
+        echo "$default_value"
+        return 1
+    fi
+
+    # Validate range
+    if [ "$value" -lt "$min_value" ] || [ "$value" -gt "$max_value" ]; then
+        echo "$default_value"
+        return 1
+    fi
+
+    echo "$value"
+    return 0
+}
+
+# Check if feature is enabled
+# Usage: if is_feature_enabled "ENABLE_POLICY_CACHING"; then ...
+is_feature_enabled() {
+    local feature_var="$1"
+    local value="${!feature_var:-0}"
+
+    case "$value" in
+        1 | true | TRUE | yes | YES | on | ON)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+# Get log level priority (for filtering)
+# Returns: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
+get_log_level_priority() {
+    local level="${1:-INFO}"
+
+    case "$level" in
+        DEBUG) echo 0 ;;
+        INFO) echo 1 ;;
+        WARN) echo 2 ;;
+        ERROR) echo 3 ;;
+        *) echo 1 ;; # Default to INFO
+    esac
+}
+
+# Check if should log at level
+# Usage: if should_log "DEBUG"; then ...
+should_log() {
+    local message_level="$1"
+    local current_priority=$(get_log_level_priority "$LOG_LEVEL")
+    local message_priority=$(get_log_level_priority "$message_level")
+
+    [ "$message_priority" -ge "$current_priority" ]
+}

package/bin/lib/detect.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Framework detection from project directory (cwd or first arg).
+# Used by bin/agent-guardrails to skip prompt when project is detectable.
+# detect_framework: echoes first detected framework or empty.
+# detect_frameworks_list: echoes all detected frameworks (space-separated, unique)
+#   so the dispatcher can show "Multiple frameworks detected: X, Y. Choose one: ...".
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+# Collect all detected framework names (unique, order: pyproject -> package.json -> requirements)
+detect_frameworks_list() {
+    local dir="${1:-.}"
+    local list=()
+
+    [[ ! -d "$dir" ]] && echo "" && return 0
+
+    # Python: pyproject.toml
+    if [[ -f "$dir/pyproject.toml" ]]; then
+        grep -qi 'langchain\|langgraph' "$dir/pyproject.toml" 2> /dev/null && list+=(langchain)
+        grep -qi 'crewai' "$dir/pyproject.toml" 2> /dev/null && list+=(crewai)
+    fi
+
+    # Node: package.json
+    if [[ -f "$dir/package.json" ]]; then
+        grep -qi 'openclaw\|open-claw\|agent-guardrails' "$dir/package.json" 2> /dev/null && list+=(openclaw)
+    fi
+
+    # requirements.txt fallback
+    if [[ -f "$dir/requirements.txt" ]]; then
+        grep -qi 'langchain' "$dir/requirements.txt" 2> /dev/null && list+=(langchain)
+        grep -qi 'crewai' "$dir/requirements.txt" 2> /dev/null && list+=(crewai)
+    fi
+
+    # Dedupe preserving order (first occurrence wins). Safe for set -u when list is empty.
+    local seen=() out=()
+    if [[ ${#list[@]} -gt 0 ]]; then
+        for fw in "${list[@]}"; do
+            if [[ " ${seen[*]:-} " != *" $fw "* ]]; then
+                seen+=("$fw")
+                out+=("$fw")
+            fi
+        done
+    fi
+    if [[ ${#out[@]} -gt 0 ]]; then
+        echo "${out[*]}"
+    else
+        echo ""
+    fi
+    return 0
+}
+
+# Return first detected framework (for single-detection behavior); empty if none.
+detect_framework() {
+    local list
+    list="$(detect_frameworks_list "${1:-.}")"
+    if [[ -n "$list" ]]; then
+        echo "${list%% *}"
+    else
+        echo ""
+    fi
+    return 0
+}
+
+export -f detect_framework detect_frameworks_list

package/bin/lib/error.sh

@@ -0,0 +1,269 @@
+#!/bin/bash
+# error.sh - Standardized error handling for APort guardrails
+# Provides consistent error codes, messages, and response formatting
+
+# Error codes (see docs/development/ERROR_CODES.md)
+readonly ERROR_INVALID_TOOL_NAME="oap.invalid_input.tool_name"
+readonly ERROR_CONTEXT_TOO_LARGE="oap.invalid_input.context_too_large"
+readonly ERROR_INVALID_AGENT_ID="oap.invalid_input.agent_id"
+readonly ERROR_PATH_NOT_ALLOWED="oap.path.not_allowed"
+readonly ERROR_PATH_TRAVERSAL="oap.path.traversal_attempt"
+readonly ERROR_PATH_INVALID_CHARS="oap.path.invalid_characters"
+readonly ERROR_PASSPORT_NOT_FOUND="oap.passport.not_found"
+readonly ERROR_PASSPORT_INVALID="oap.passport.invalid_format"
+readonly ERROR_PASSPORT_EXPIRED="oap.passport.expired"
+readonly ERROR_PASSPORT_REVOKED="oap.passport.revoked"
+readonly ERROR_PASSPORT_MISSING_CAP="oap.passport.missing_capability"
+readonly ERROR_POLICY_NOT_FOUND="oap.policy.not_found"
+readonly ERROR_POLICY_INVALID="oap.policy.invalid_format"
+readonly ERROR_POLICY_EVAL_FAILED="oap.policy.evaluation_failed"
+readonly ERROR_POLICY_TIMEOUT="oap.policy.evaluation_timeout"
+readonly ERROR_POLICY_DENIED="oap.policy.denied"
+readonly ERROR_API_CONNECTION="oap.api.connection_failed"
+readonly ERROR_API_AUTH="oap.api.authentication_failed"
+readonly ERROR_API_RATE_LIMIT="oap.api.rate_limit_exceeded"
+readonly ERROR_API_TIMEOUT="oap.api.timeout"
+readonly ERROR_API_ERROR="oap.api.error"
+readonly ERROR_CONFIG_NOT_FOUND="oap.config.not_found"
+readonly ERROR_CONFIG_INVALID="oap.config.invalid_format"
+readonly ERROR_EVALUATOR_ERROR="oap.system.evaluator_error"
+readonly ERROR_COMMAND_INJECTION="oap.system.command_injection_detected"
+readonly ERROR_DEPENDENCY_MISSING="oap.system.dependency_missing"
+readonly ERROR_MISCONFIGURED="oap.misconfigured"
+
+# Generate unique request ID
+generate_request_id() {
+    local timestamp=$(date +%s%3N 2> /dev/null || date +%s)
+    local random=$(openssl rand -hex 3 2> /dev/null || echo "$RANDOM")
+    echo "req_${timestamp}_${random}"
+}
+
+# Generate ISO 8601 timestamp
+generate_timestamp() {
+    date -u +"%Y-%m-%dT%H:%M:%S.%3NZ" 2> /dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+# Format error as JSON decision
+# Usage: format_error_json "error_code" "message" ["details_json"] ["resolution"]
+format_error_json() {
+    local code="$1"
+    local message="$2"
+    local details="${3:-}"
+    local resolution="${4:-}"
+    local request_id="${5:-$(generate_request_id)}"
+    local timestamp=$(generate_timestamp)
+
+    local reason_json
+    reason_json=$(
+        cat << EOF
+{
+  "code": "$code",
+  "message": "$message"
+}
+EOF
+    )
+
+    # Add details if provided
+    if [ -n "$details" ]; then
+        reason_json=$(echo "$reason_json" | jq -c --argjson d "$details" '. + {details: $d}')
+    fi
+
+    # Add resolution if provided
+    if [ -n "$resolution" ]; then
+        reason_json=$(echo "$reason_json" | jq -c --arg r "$resolution" '. + {resolution: $r}')
+    fi
+
+    # Create full response
+    cat << EOF
+{
+  "allow": false,
+  "reasons": [$reason_json],
+  "request_id": "$request_id",
+  "timestamp": "$timestamp"
+}
+EOF
+}
+
+# Format error as plain text
+# Usage: format_error_text "error_code" "message" ["details"] ["resolution"]
+format_error_text() {
+    local code="$1"
+    local message="$2"
+    local details="${3:-}"
+    local resolution="${4:-}"
+    local request_id="${5:-$(generate_request_id)}"
+
+    echo "ERROR: $code"
+    echo "$message"
+
+    if [ -n "$details" ]; then
+        echo "Details: $details"
+    fi
+
+    if [ -n "$resolution" ]; then
+        echo ""
+        echo "Resolution:"
+        echo "$resolution"
+    fi
+
+    echo ""
+    echo "Request ID: $request_id"
+}
+
+# Write error to stderr in text format
+# Usage: error_log "error_code" "message" ["details"]
+error_log() {
+    local code="$1"
+    local message="$2"
+    local details="${3:-}"
+
+    format_error_text "$code" "$message" "$details" >&2
+}
+
+# Write deny decision to decision file
+# Usage: write_deny_decision "error_code" "message" ["details"] ["resolution"]
+write_deny_decision() {
+    local code="$1"
+    local message="$2"
+    local details="${3:-}"
+    local resolution="${4:-}"
+
+    if [ -z "$DECISION_FILE" ]; then
+        error_log "oap.system.evaluator_error" "DECISION_FILE not set"
+        return 1
+    fi
+
+    format_error_json "$code" "$message" "$details" "$resolution" > "$DECISION_FILE" 2> /dev/null || true
+}
+
+# Write allow decision to decision file
+# Usage: write_allow_decision "message" ["policy_id"]
+write_allow_decision() {
+    local message="${1:-All policy checks passed}"
+    local policy_id="${2:-}"
+    local request_id=$(generate_request_id)
+    local timestamp=$(generate_timestamp)
+
+    if [ -z "$DECISION_FILE" ]; then
+        error_log "oap.system.evaluator_error" "DECISION_FILE not set"
+        return 1
+    fi
+
+    local decision_json
+    decision_json=$(
+        cat << EOF
+{
+  "allow": true,
+  "reasons": [{"message": "$message"}],
+  "request_id": "$request_id",
+  "timestamp": "$timestamp"
+}
+EOF
+    )
+
+    # Add policy_id if provided
+    if [ -n "$policy_id" ]; then
+        decision_json=$(echo "$decision_json" | jq -c --arg p "$policy_id" '. + {policy_id: $p}')
+    fi
+
+    echo "$decision_json" > "$DECISION_FILE" 2> /dev/null || true
+}
+
+# Get standard resolution message for error code
+# Usage: resolution=$(get_resolution "error_code")
+get_resolution() {
+    local code="$1"
+
+    case "$code" in
+        "$ERROR_INVALID_TOOL_NAME")
+            echo "Use only alphanumeric characters, dots, underscores, and hyphens in tool names. Keep tool names under 128 characters."
+            ;;
+        "$ERROR_CONTEXT_TOO_LARGE")
+            echo "Reduce context data size by removing unnecessary fields or summarizing large data. Default limit: 100KB."
+            ;;
+        "$ERROR_PATH_NOT_ALLOWED")
+            echo "Use standard APort directories: ~/.openclaw/, ~/.aport/, or /tmp/aport-*. Contact administrator to add custom allowed directories."
+            ;;
+        "$ERROR_PATH_TRAVERSAL")
+            echo "Use absolute paths without parent directory references (../ or /..). This is a security feature to prevent path traversal attacks."
+            ;;
+        "$ERROR_PASSPORT_NOT_FOUND")
+            echo "Create a passport by running: npx @aporthq/agent-guardrails openclaw. See: https://github.com/aporthq/agent-guardrails#passport-setup"
+            ;;
+        "$ERROR_PASSPORT_MISSING_CAP")
+            echo "Request capability be added to passport or generate new passport with required capabilities."
+            ;;
+        "$ERROR_POLICY_NOT_FOUND")
+            echo "Verify policy pack ID is correct and update policy submodule: git submodule update --init --recursive"
+            ;;
+        "$ERROR_API_CONNECTION")
+            echo "Check internet connectivity, verify API URL (APORT_API_URL), and check firewall allows outbound HTTPS."
+            ;;
+        "$ERROR_API_AUTH")
+            echo "Verify API key is set (APORT_API_KEY) and generate new API key if needed from APort dashboard."
+            ;;
+        "$ERROR_API_RATE_LIMIT")
+            echo "Wait for rate limit to reset, reduce request frequency, or use local evaluation mode instead of API mode."
+            ;;
+        "$ERROR_MISCONFIGURED")
+            echo "Run setup: npx @aporthq/agent-guardrails <framework>. Check passport exists at ~/.openclaw/passport.json"
+            ;;
+        *)
+            echo ""
+            ;;
+    esac
+}
+
+# Helper: Write error and exit
+# Usage: die "error_code" "message" ["details"]
+die() {
+    local code="$1"
+    local message="$2"
+    local details="${3:-}"
+    local resolution=$(get_resolution "$code")
+
+    write_deny_decision "$code" "$message" "$details" "$resolution"
+    error_log "$code" "$message" "$details"
+    exit 1
+}
+
+# Validate required command exists
+# Usage: require_command "jq"
+require_command() {
+    local cmd="$1"
+    local install_hint="${2:-}"
+
+    if ! command -v "$cmd" > /dev/null 2>&1; then
+        local details="{\"command\":\"$cmd\"}"
+        local message="Required command not found: $cmd"
+
+        if [ -n "$install_hint" ]; then
+            message="$message. Install with: $install_hint"
+        fi
+
+        die "$ERROR_DEPENDENCY_MISSING" "$message" "$details"
+    fi
+}
+
+# Check if decision file is writable
+# Usage: check_decision_file_writable
+check_decision_file_writable() {
+    if [ -z "$DECISION_FILE" ]; then
+        error_log "oap.system.evaluator_error" "DECISION_FILE not set"
+        return 1
+    fi
+
+    local decision_dir=$(dirname "$DECISION_FILE")
+
+    if [ ! -d "$decision_dir" ]; then
+        error_log "oap.system.insufficient_permissions" "Decision directory does not exist: $decision_dir"
+        return 1
+    fi
+
+    if [ ! -w "$decision_dir" ]; then
+        error_log "oap.system.insufficient_permissions" "Cannot write to decision directory: $decision_dir"
+        return 1
+    fi
+
+    return 0
+}

package/bin/lib/passport.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Passport creation wizard logic (shared across frameworks)
+# OAP v1.0 format; used by bin/aport-create-passport.sh and framework installers.
+
+# shellcheck source=./common.sh
+source "$(dirname "${BASH_SOURCE[0]:-.}")/common.sh"
+
+# Placeholder: full wizard logic can be refactored from aport-create-passport.sh
+run_passport_wizard() {
+    log_info "Running passport wizard (shared)..."
+    # Delegate to existing script if present
+    if [[ -x "$ROOT_DIR/bin/aport-create-passport.sh" ]]; then
+        "$ROOT_DIR/bin/aport-create-passport.sh" "$@"
+    else
+        log_warn "bin/aport-create-passport.sh not found; wizard stub only."
+    fi
+}
+
+export -f run_passport_wizard

package/bin/lib/templates/.gitkeep

@@ -0,0 +1 @@
+# Config templates per framework (e.g. aport-config.yaml, config.json)

package/bin/lib/templates/config.yaml

@@ -0,0 +1,6 @@
+# APort agent guardrails config (shared template for langchain, crewai, n8n)
+# mode: api | local
+# For API: set agent_id (hosted passport). For local: set passport_path.
+mode: local
+# agent_id: ap_xxx
+# passport_path: ~/.aport/passport.json