@aporthq/aport-agent-guardrails 1.0.28 → 1.0.29

package/README.md

@@ -96,6 +96,7 @@ npx --yes @aporthq/aport-agent-guardrails claude-code --non-interactive
 
 - **I need OpenClaw now:** [docs/QUICKSTART_OPENCLAW_PLUGIN.md](docs/QUICKSTART_OPENCLAW_PLUGIN.md)
 - **I already have agent_id:** [docs/HOSTED_PASSPORT_SETUP.md](docs/HOSTED_PASSPORT_SETUP.md)
+- **I’m deploying for an IT team:** [docs/ENTERPRISE_DEVICE_DEPLOYMENT.md](docs/ENTERPRISE_DEVICE_DEPLOYMENT.md)
 - **I need framework setup docs:** [docs/frameworks](docs/frameworks)
 - **I want Claude marketplace install:** [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md#marketplace-install-claude-plugins)
 
@@ -118,7 +119,7 @@ The security concern is that agent tools and skills can execute sensitive action
 
 **Two ways to use APort:** (1) **Guardrails (CLI/setup)** — run the installer to create your passport and config; (2) **Core (library)** — use the `OAPGuardrailProvider` ([docs/PROVIDER.md](docs/PROVIDER.md)) in your app so each tool call is verified. One provider per language (Python + TypeScript), works with any framework. Framework docs: [OpenClaw](docs/frameworks/openclaw.md), [Cursor](docs/frameworks/cursor.md), [Claude Code](docs/frameworks/claude-code.md), [LangChain](docs/frameworks/langchain.md), [CrewAI](docs/frameworks/crewai.md), [DeerFlow](docs/frameworks/deerflow.md), [n8n](docs/frameworks/n8n.md).
 
-**CLI-supported frameworks:** `openclaw`, `langchain`, `crewai`, `cursor`, `claude-code`, `deerflow`, `n8n`. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. See [Deployment readiness](docs/DEPLOYMENT_READINESS.md).
+**CLI-supported frameworks:** `openclaw`, `langchain`, `crewai`, `cursor`, `claude-code`, `deerflow`, `n8n`. OpenClaw/Cursor/Claude Code include runtime-specific integration scripts; DeerFlow/LangChain/CrewAI use framework docs plus generic setup output from the CLI. For IT-managed device rollout, see [Enterprise device deployment](docs/ENTERPRISE_DEVICE_DEPLOYMENT.md).
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|

package/bin/frameworks/generic.sh

@@ -48,7 +48,11 @@ while [[ ${#remaining_args[@]} -gt 0 ]]; do
             crewai_integration_mode="${remaining_args[0]}"
             remaining_args=("${remaining_args[@]:1}")
             ;;
-        ap_[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])
+        ap_* | apt_* | agt_inst_* | agt_tmpl_*)
+            if ! is_aport_hosted_agent_id "$arg"; then
+                log_error "Invalid hosted passport ID format: $arg"
+                exit 1
+            fi
             hosted_agent_id="$arg"
             ;;
         *)

package/bin/lib/guardrail-mode.sh

@@ -5,6 +5,10 @@
 
 DEFAULT_APORT_API_URL="${DEFAULT_APORT_API_URL:-https://api.aport.io}"
 
+is_aport_hosted_agent_id() {
+    [[ "${1:-}" =~ ^(ap|apt|agt_inst|agt_tmpl)_[A-Za-z0-9_-]+$ ]]
+}
+
 parse_guardrail_mode_args() {
     APORT_GUARDRAIL_MODE_CLI="${APORT_GUARDRAIL_MODE_CLI:-}"
     APORT_GUARDRAIL_API_URL_CLI="${APORT_GUARDRAIL_API_URL_CLI:-}"
@@ -66,7 +70,11 @@ parse_guardrail_mode_args() {
                 APORT_ISSUE_URL_CLI="$2"
                 shift
                 ;;
-            ap_[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9])
+            ap_* | apt_* | agt_inst_* | agt_tmpl_*)
+                if ! is_aport_hosted_agent_id "$1"; then
+                    echo "[aport] ERROR: Invalid hosted passport ID format: $1" >&2
+                    return 1
+                fi
                 APORT_HOSTED_AGENT_ID_CLI="$1"
                 ;;
             *)

package/bin/openclaw

@@ -126,12 +126,12 @@ if [ -n "${1:-}" ]; then
 		echo "See: https://github.com/aporthq/aport-agent-guardrails/tree/main/docs"
 		exit 0
 	fi
-	# Validate agent_id format (ap_ followed by 32 hex chars)
-	if [[ "$1" =~ ^ap_[a-f0-9]{32}$ ]]; then
+	# Validate agent_id format.
+	if [[ "$1" =~ ^(ap|apt|agt_inst|agt_tmpl)_[A-Za-z0-9_-]+$ ]]; then
 		HOSTED_AGENT_ID="$1"
 	else
 		echo "❌ Invalid agent_id format: $1"
-		echo "   Expected: ap_[32 hex characters]"
+		echo "   Expected: ap_..., apt_..., agt_inst_..., or agt_tmpl_..."
 		echo "   Example: ap_fa2f6d53bb5b4c98b9af0124285b6e0f"
 		echo ""
 		echo "Run '$0 --help' for usage information."

package/docs/ENTERPRISE_DEVICE_DEPLOYMENT.md

@@ -0,0 +1,153 @@
+# Enterprise Device Deployment
+
+Use this guide when an IT team wants to deploy APort guardrails to one or many developer machines through a device-management tool, remote shell, or manual test run.
+
+The deployment scripts are generic. They work for MDM tools, endpoint-management tools, remote shell runners, or a saved script executed by an administrator.
+
+## What Gets Installed
+
+The deploy script:
+
+1. Identifies the target device and user.
+2. Reuses an existing passport instance for that device when one already exists.
+3. Creates a new instance from the template passport only when needed.
+4. Mints a narrow runtime setup key for that instance.
+5. Runs `npx @aporthq/aport-agent-guardrails <framework> <agent_id> --mode=api`.
+6. Writes the framework hook/config for the target user.
+
+The org enrollment key is not stored for runtime. Hooks use the minted runtime key.
+
+## Requirements
+
+Each target device needs:
+
+- Node.js 18+
+- npm/npx
+- curl
+- The target agent framework installed or available to the developer, for example Claude Code or Cursor
+
+APort setup requires:
+
+- A template passport in the APort org.
+- An org API key with `issue` scope. Use the narrowest key available; do not use a broad admin key.
+- The framework name, for example `claude-code` or `cursor`.
+
+## Recommended First Test
+
+Run the deploy script on one developer test machine first.
+
+```bash
+export APORT_API_KEY="apk_..."
+export APORT_TEMPLATE_ID="ap_..."
+export APORT_FRAMEWORK="claude-code"
+
+curl -fsSL "https://api.aport.io/enterprise/scripts/deploy?version=1.0.29" | bash
+```
+
+If the script runs as `root`, set the developer account explicitly:
+
+```bash
+export APORT_TARGET_USER="developer"
+export APORT_TARGET_HOME="/Users/developer"
+```
+
+For Linux, `APORT_TARGET_HOME` is usually `/home/<user>`.
+
+## Script Commands
+
+| Command | URL | Purpose |
+| --- | --- | --- |
+| Deploy | `https://api.aport.io/enterprise/scripts/deploy?version=1.0.29` | Initial install or repair |
+| Enforce | `https://api.aport.io/enterprise/scripts/enforce?version=1.0.29` | Validate state and reinstall if the hook/config is missing |
+| Uninstall | `https://api.aport.io/enterprise/scripts/uninstall?version=1.0.29` | Remove APort-owned wiring and local state |
+
+Use `deploy` for the first test. Use `enforce` as the recurring compliance script. Use `uninstall` only for approved removal.
+
+## Configuration Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `APORT_API_KEY` | Deploy/enforce | Org enrollment key with `issue` scope |
+| `APORT_TEMPLATE_ID` | Deploy/enforce | Template passport ID to instantiate per device/user |
+| `APORT_FRAMEWORK` | All | `claude-code`, `cursor`, `openclaw`, `langchain`, `crewai`, `deerflow`, or `n8n` |
+| `APORT_API_URL` | No | Defaults to `https://api.aport.io` |
+| `APORT_TARGET_USER` | No | Developer account that runs the agent framework |
+| `APORT_TARGET_HOME` | No | Home/profile directory for the target user |
+| `APORT_DEVICE_ID` | No | Stable device identifier; auto-detected when unset |
+| `APORT_STATE_DIR` | No | Override local system state directory |
+| `DISABLE_DEVICE_INFO` | No | Set to `1` to skip device metadata collection |
+
+## How Device Identity Works
+
+The script derives a stable `tenant_ref` from:
+
+- device ID
+- target username
+- framework
+- template passport ID
+
+This prevents duplicate passport instances when the deploy or enforce script runs again on the same device for the same user/framework/template.
+
+Device ID is auto-detected from:
+
+- macOS: hardware serial number
+- Linux: machine ID
+- Windows: BIOS serial number
+- fallback: hostname
+
+Set `APORT_DEVICE_ID` if the device-management system has a stronger stable identifier.
+
+## Verify The Install
+
+After deploy:
+
+1. Open APort and switch to the org context.
+2. Open the template passport.
+3. Confirm an instance exists for the test device.
+4. Ask the developer to run a normal Claude Code or Cursor task.
+5. Confirm allow/deny decisions appear in APort audit.
+
+For a pilot, use a test repository and prompts that exercise both normal developer actions and blocked actions, for example safe repo inspection, test execution, destructive cleanup, privileged commands, and sensitive file reads.
+
+## Enforcement Script
+
+Run this as the recurring compliance check:
+
+```bash
+export APORT_API_KEY="apk_..."
+export APORT_TEMPLATE_ID="ap_..."
+export APORT_FRAMEWORK="claude-code"
+
+curl -fsSL "https://api.aport.io/enterprise/scripts/enforce?version=1.0.29" | bash
+```
+
+`enforce` reuses existing local state when present. If the framework hook/config is missing, it reinstalls without creating a duplicate passport instance.
+
+## Uninstall
+
+Use only for approved removal:
+
+```bash
+export APORT_FRAMEWORK="claude-code"
+
+curl -fsSL "https://api.aport.io/enterprise/scripts/uninstall?version=1.0.29" | bash
+```
+
+Uninstall removes APort-owned framework wiring and local APort state for the selected framework. It does not delete the passport or audit records from APort.
+
+## Auditable Download
+
+For stricter change-control, fetch the manifest and verify the script hash before execution:
+
+```bash
+curl -fsSL "https://api.aport.io/enterprise/scripts?version=1.0.29"
+curl -fsSL "https://api.aport.io/enterprise/scripts/deploy?version=1.0.29" -o /tmp/aport-deploy.sh
+shasum -a 256 /tmp/aport-deploy.sh
+bash /tmp/aport-deploy.sh
+```
+
+Compare the `shasum` output to the manifest’s `sha256` value.
+
+## More Detail
+
+The source scripts and implementation notes are in [`enterprise-scripts/README.md`](../enterprise-scripts/README.md).

package/docs/README.md

@@ -7,6 +7,7 @@
 | [QUICKSTART_OPENCLAW_PLUGIN.md](QUICKSTART_OPENCLAW_PLUGIN.md) | **OpenClaw plugin** — one-command setup, deterministic enforcement (RECOMMENDED) |
 | [**HOSTED_PASSPORT_SETUP.md**](HOSTED_PASSPORT_SETUP.md) | **Use passport from aport.io** — create hosted during setup or pass `npx @aporthq/aport-agent-guardrails openclaw <agent_id>` |
 | [QUICKSTART.md](QUICKSTART.md) | Interactive setup and step-by-step hosted/local passport options |
+| [ENTERPRISE_DEVICE_DEPLOYMENT.md](ENTERPRISE_DEVICE_DEPLOYMENT.md) | IT-managed deploy, enforce, and uninstall scripts |
 | [OPENCLAW_LOCAL_INTEGRATION.md](OPENCLAW_LOCAL_INTEGRATION.md) | Full OpenClaw setup: API, passport, policies, Python example |
 | [OPENCLAW_TOOLS_AND_POLICIES.md](OPENCLAW_TOOLS_AND_POLICIES.md) | exec, allowed_commands, unmapped tools, passport limits |
 | [TOOL_POLICY_MAPPING.md](TOOL_POLICY_MAPPING.md) | How tool names map to policy packs |

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.28 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.29 (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.
 

package/extensions/openclaw-aport/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog - APort OpenClaw Plugin
 
+## 1.0.29
+
 ## 1.0.28
 
 ## 1.0.27

package/extensions/openclaw-aport/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-aport",
   "name": "APort Guardrails",
   "description": "Deterministic pre-action authorization via APort policy enforcement. Registers before_tool_call to block disallowed tools.",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/extensions/openclaw-aport/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@aporthq/openclaw-aport",
-      "version": "1.0.28",
+      "version": "1.0.29",
       "license": "Apache-2.0",
       "devDependencies": {
         "@types/node": "^18.0.0",

package/extensions/openclaw-aport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "description": "OpenClaw plugin for deterministic pre-action authorization via APort guardrails",
   "main": "index.js",
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",