@dexgate/openclaw-trusted-mode

v1.0.18

Published

a month ago

MIT-licensed OpenClaw Trusted Mode: free local allowlist by default; opt-in MIDDLEWARE path to @dexgate/decision-middleware + SDE PDP

0High
0Medium
0Low

dexgateops

tmdarke

openclaw trusted-mode policy-enforcement governance security dexgate clawhub local-hardening

@dexgate/openclaw-trusted-mode

OpenClaw plugin that enforces Trusted Mode policy checks on before_tool_call.

Links

| | | |---|---| | Product | dexgate.ai | | OpenClaw quickstart | dexgate.ai/docs/openclaw/quickstart | | Pricing | dexgate.ai/pricing | | Customer console | dexgate.ai/console | | GitHub | github.com/dexgate-ai/openclaw-trusted-mode | | npm | @dexgate/openclaw-trusted-mode | | X | @dexgateAI | | Contact | dexgate.ai/contact |

First-time setup in this repo: START_HERE.md.
Terminology: GLOSSARY.md. Docs index: docs/README.md.

Acronym Expansions

SDE: Strategic Decision Engine
PDP: Policy Decision Point
PEP: Policy Enforcement Point
WSL: Windows Subsystem for Linux
CI: Continuous Integration

Quick start (free)

npm install @dexgate/openclaw-trusted-mode
# or
openclaw plugins install npm:@dexgate/openclaw-trusted-mode

Then follow the hosted guide: OpenClaw quickstart.
Repo walkthrough: START_HERE.md.

Install uses the latest dist-tag only (no separate pilot channel).

What you get immediately (free / default): a local hard gate on tool calls—safer defaults, no network, no account required.
When you are ready: the same plugin can switch to the full governed path (Decision Middleware + SDE PDP) for real policy decisions, evidence, and multi-environment control. See Free vs governed below.

Free vs governed (authorization modes)

Dexgate Trusted Mode is designed as a smooth upgrade, not a rewrite. You install once; you choose how strict authorization is.

| Mode | Default? | What you get | Network | |------|----------|--------------|---------| | ALLOWLIST_ONLY | Yes (free) | Local hard gate: only tools you list may run. Everything else is blocked in-process. | None | | MIDDLEWARE | Opt-in | Full governed path: OpenClaw → Decision Middleware → SDE PDP. Allow / deny / constrain with trace_id + reconstructible evidence. Fail-closed if the stack is unreachable. | Local or private services only | | PDP | Opt-in (legacy) | Direct call to SDE PDP /v1/authorize (still supported). Prefer MIDDLEWARE for new setups. | Direct to PDP |

What free mode gives you today

With toolPolicyMode: "ALLOWLIST_ONLY" (the default):

Safer out-of-box defaults (e.g. read_file, list_files, search_files)
High-risk tools (shell, writes, deletes, …) stay off unless you deliberately expand the list
Works offline; nothing leaves the machine
Same plugin surface you will use when you turn on governance later

This is the right place to start for local agents, demos, and “just make OpenClaw less reckless.”

What you gain on the full governed path

When you enable MIDDLEWARE and run Decision Middleware + SDE PDP:

| Capability | Free (allowlist) | Governed (middleware + PDP) | |------------|------------------|-----------------------------| | Block unknown tools | Yes (static list) | Yes (policy decision) | | Context-aware allow / deny | No | Yes (tool + args + environment + trust signals) | | trace_id + evidence per call | No | Yes (reconstructible proposal, policy version, risk signals) | | Fail-closed if decision path is down | N/A (local only) | Yes (default) | | Dev / staging / production profiles | Manual list only | Environment-aware policy via SDE | | Action Passports | No | Middleware /v1/decide returns passport: null (field reserved in the v0.1 envelope). Entitled SDE runtime workflows issue, verify, expire, and revoke Passports separately (protected-executor path)—not via the middleware decide response itself. |

Stack:

OpenClaw  →  Decision Middleware (:8787 /v1/decide)  →  SDE PDP (:8001 /v1/authorize)

| Component | Role | Package / location | |-----------|------|--------------------| | This plugin | OpenClaw PEP (before_tool_call) | @dexgate/openclaw-trusted-mode (you are here) | | Decision Middleware | Contract + evidence + fail-closed client to PDP | @dexgate/decision-middleware (c:\dev\dexgate-decision-middleware) | | SDE PDP | Authoritative policy (signed packs, entitlements) | Licensed sde-enterprise runtime |

Important: Free mode does not require the decision middleware package or the SDE PDP. Those are only for opt-in MIDDLEWARE (or legacy PDP) mode. This adapter talks to the middleware over HTTP (no hard npm dependency), so free installs stay lightweight and offline-safe.

Live verification runbook: docs/LIVE_GOVERNED_PATH_VERIFICATION.md.
Product messaging draft for the site: docs/FREE_TO_GOVERNED_MESSAGING.md.
QA website copy blocks: docs/QA_SITE_COPY_FREE_TO_GOVERNED.md.
Controlled release checklist: RELEASE_CHECKLIST.md.

Quick upgrade (minimal config change)

Before (free):

{
  "toolPolicyMode": "ALLOWLIST_ONLY",
  "allowedTools": ["read_file", "list_files", "search_files"]
}

After (governed via middleware):

{
  "toolPolicyMode": "MIDDLEWARE",
  "decisionMiddlewareUrl": "http://127.0.0.1:8787/v1/decide",
  "environment": "dev",
  "failClosed": true,
  "enforcementPosture": "fail-closed",
  "policyVariant": "guard-pro.v2026.02",
  "decisionSku": "openclaw.trusted_mode.authorize.v1",
  "tenantId": "trial-tenant",
  "gatewayId": "gw-dev"
}

That is the essential switch: ALLOWLIST_ONLY → MIDDLEWARE, plus the decide URL and environment.
Env equivalent: DEXGATE_TOOL_POLICY_MODE=MIDDLEWARE and optional DEXGATE_DECISION_MIDDLEWARE_URL.

Startup order for governed mode:

Start SDE PDP (e.g. http://127.0.0.1:8001)
Start Decision Middleware with SDE_PDP_URL=http://127.0.0.1:8001/v1/authorize (port 8787)
Point this plugin at the middleware as above
Confirm: logs show decision=… and trace_id=…

[Trusted Mode] middleware tool=read_file decision=allow trace_id=… reason=…
[Trusted Mode] middleware tool=shell decision=deny trace_id=… reason=…

# After middleware + PDP are up:
npm run build
npm run verify-live-governed-path

Offline shape check (mock middleware, no PDP): npm run verify-decision-middleware

Free vs governed at a glance

FREE (default)                         GOVERNED (upgrade)
─────────────────                      ──────────────────────────────
Plugin only                            Plugin + Decision Middleware + SDE PDP
Static allowlist                       Real policy evaluation
No trace / evidence                    trace_id + evidence per tool call
No network                             Private/local decision services
Good for day-one safety                Good for teams, prod controls, audit trail

You keep the same OpenClaw plugin either way. Upgrade is a mode change, not a new product install for the adapter itself. Licensed SDE runtime / commercial terms apply to the governed control plane—see Licensing and the customer console.

npm Package

Install the public MIT adapter/plugin package with:

npm install @dexgate/openclaw-trusted-mode

ClawHub discovery

ClawHub is OpenClaw's plugin discovery surface. See CLAWHUB.md.

openclaw plugins search "dexgate"
openclaw plugins install clawhub:@dexgate/openclaw-trusted-mode
# or npm:
openclaw plugins install npm:@dexgate/openclaw-trusted-mode

What `npm install` gives you

npm install @dexgate/openclaw-trusted-mode gives you the MIT adapter/plugin layer and standalone hardening flow only. It does not grant access to the proprietary SDE runtime, enterprise deployment packs, or governed tenant entitlements.

Authorization paths (reference)

| Mode | Who | Network | Config keys | |------|-----|---------|-------------| | ALLOWLIST_ONLY (default) | Free / local | None | allowedTools | | MIDDLEWARE (preferred governed) | Teams running Decision Middleware + SDE | POST …/v1/decide | decisionMiddlewareUrl, environment, … | | PDP (legacy governed) | Direct SDE | POST …/v1/authorize | pdpUrl, tenantId, gatewayId, environment |

Free / local path

{
  "toolPolicyMode": "ALLOWLIST_ONLY",
  "allowedTools": ["read_file", "list_files", "search_files"]
}

No PDP, no middleware, no network. Tools not on the allowlist are blocked.

Governed path via decision middleware (preferred)

Run SDE PDP (e.g. http://127.0.0.1:8001).
Run Decision Middleware (port 8787, SDE_PDP_URL → PDP authorize).
Set toolPolicyMode to MIDDLEWARE (see Quick upgrade).

Env overrides:

| Variable | Purpose | |----------|---------| | DEXGATE_TOOL_POLICY_MODE | ALLOWLIST_ONLY | MIDDLEWARE | PDP | | DEXGATE_DECISION_MIDDLEWARE_URL / DEXGATE_MIDDLEWARE_URL | Decide endpoint (default http://127.0.0.1:8787/v1/decide) | | PDP_AUTH_TOKEN | Only for legacy direct PDP path |

Fail-closed: if the middleware is down or returns an error, the tool call is blocked when failClosed is true (default).

Full live checklist: docs/LIVE_GOVERNED_PATH_VERIFICATION.md.

Need licensed SDE / enterprise?

Obtain your licensed SDE runtime from the dexgate customer console. Use this npm package as the OpenClaw adapter, then connect Decision Middleware + SDE for governed authorization and evidence.

The npm package contains the MIT plugin files and standalone hardening logic only.
It does not include the proprietary sde-enterprise runtime.

Licensing

openclaw-trusted-mode is licensed under the MIT License.

sde-enterprise, including the SDE PDP runtime and related enterprise deployment assets, is proprietary software and is not covered by the plugin's MIT license. Use, copying, modification, distribution, or deployment of the SDE runtime requires a separate commercial license or written permission from Automated Decision Systems, LLC.

First-time setup (download/install/configure/test/run): START_HERE.md. Troubleshooting decision tree: SELF_SERVICE_FAQ.md. Org defaults and support metadata are delivered through the customer console and the licensed runtime-secrets package. One-command setup is generated per customer in the console Downloads page alongside the licensed runtime bundle. For full install/reinstall/uninstall/startup/config/troubleshooting guidance across both plugin and SDE-PDP, see OPERATIONS_GUIDE.md. For a simpler operator runbook, see RUNBOOK_NON_TECHNICAL.md. For go-live gating, use PRODUCTION_READINESS_CHECKLIST.md. For a pre-filled starting point, use PRODUCTION_READINESS_CHECKLIST_EXAMPLE.md. For alternate port deployments, use PRODUCTION_READINESS_CHECKLIST_EXAMPLE_ALT_PORTS.md. For public launch readiness, use PUBLIC_RELEASE_READINESS_CHECKLIST.md. For end-to-end public release execution steps (what/where/how), use PUBLIC_RELEASE_PROCESS_RUNBOOK.md. For certified runtime support status, see COMPATIBILITY_MATRIX.md. For vulnerability reporting and security posture, see SECURITY.md. For release hardening process, see RELEASE_OPERATIONS.md. For security evidence indexing, see SECURITY_EVIDENCE_BUNDLE.md. For performance baseline evidence, see PERFORMANCE_BASELINE.md. For governed release declaration, see RELEASE_v1.0.0.md.

What it does

Free standalone mode defaults to local hardening with a minimal allowlist:
- read_file
- list_files
- search_files
Blocks high-risk tools such as exec, file writes/edits, and deletes unless you deliberately widen the policy.
Sends tool call context to a Policy Decision Point (PDP) endpoint.
Denies execution when PDP returns a deny decision.
Optionally enforces returned constraints.
Supports fail-closed (default) or fail-open behavior.

Free vs Paid

The product boundary should be explicit at install time:

npm install gets you the adapter/plugin and standalone hardening path
governed mode requires a separately licensed SDE deployment
the customer console is the supported way to obtain governed runtime artifacts and deployment instructions
Free standalone use:
- useful as a local hardening layer
- works without sde-enterprise
- best for "read/search only" OpenClaw sessions
Paid / enterprise use:
- PDP-backed authorization and deny decisions
- local integrity-checked policy packs
- tenant entitlements and governed rollout
- local integrity evidence and compatibility certification

Build and test

npm run build
npm test
npm run adversarial-check
npm run performance-benchmark
npm run test-pack-matrix

Trusted Mode Check

npm run trusted-mode-check
npm run trusted-mode-check -- --json

trusted-mode-check is a PDP-backed validation path. It is useful for SDE-integrated deployments, not for standalone free-mode validation.

JSON output status values:

ENFORCED_OK
LOCKDOWN_ONLY
UNSAFE

The JSON output also includes the exact governed context it checked:

pdp_url
tenant_id
gateway_id
environment

Use those fields first when a governed check fails. If dexgate is reachable but denies the request, confirm the workspace is licensed and the tenant, gateway, and environment values match the dexgate runtime you installed.

Local integrity check inputs:

attestation/trusted_mode_attest_v1.json
attestation/trusted_mode_attest_v1.sig (SHA-256 checksum file; retained filename for compatibility)

Runtime/certification env vars:

CERTIFICATION_STATUS (CERTIFIED_ENFORCED | LOCKDOWN_ONLY | UNSUPPORTED)
OPENCLAW_VERSION
EXPECTED_STATUS (optional CI assertion override)
PDP_AUTH_TOKEN or DEXGATE_PDP_AUTH_TOKEN (optional bearer token for licensed PDP authentication)

Local install in OpenClaw (WSL)

openclaw plugins install /mnt/c/path/to/openclaw-trusted-mode
openclaw plugins info openclaw-trusted-mode

For a standalone free-mode config, start from openclaw.user-config.entry.example.json.

For governed mode, install/register the plugin first, then write the OpenClaw host config with:

openclaw-trusted-mode-configure \
  --tenantId dexgate \
  --gatewayId gw-dev \
  --environment dev \
  --pdpUrl http://10.90.0.6:8001/v1/authorize \
  --pdpAuthToken <runtime-token> \
  --certificationStatus LOCKDOWN_ONLY

This command updates ~/.openclaw/openclaw.json, adds openclaw-trusted-mode to plugins.allow, and writes the governed plugin settings under plugins.entries.openclaw-trusted-mode.

Plugin config

See openclaw.plugin.json for config schema and defaults, including:

pdpUrl
pdpAuthToken
policyVariant
pdpTimeoutMs
failClosed
tenantId
certificationStatus
openclawVersion
certifiedOpenClawVersions
highRiskTools
toolPolicyMode
allowedTools
requireTenantId
allowedTenantIds
contextCurator

Recommended standalone free-mode baseline:

{
  "toolPolicyMode": "ALLOWLIST_ONLY",
  "allowedTools": ["read_file", "list_files", "search_files"],
  "failClosed": true,
  "certificationStatus": "LOCKDOWN_ONLY"
}

Recommended paid / PDP-backed baseline:

{
  "toolPolicyMode": "PDP",
  "pdpUrl": "http://localhost:8001/v1/authorize",
  "pdpAuthToken": "<runtime-token>",
  "tenantId": "trial-tenant",
  "gatewayId": "gw-smoke-1",
  "environment": "prod",
  "failClosed": true,
  "certificationStatus": "LOCKDOWN_ONLY"
}

Compatibility Matrix Automation

npm run update-compatibility-matrix
npm run verify-compatibility-matrix

Security Gates

npm run collect-security-evidence
npm run generate-security-release-index
npm run verify-security-gates

Schema Contract and Evidence Bundle

npm run verify-plugin-schema-contract
npm run bundle-release-evidence

Startup Health Verification

npm run startup-health-check -- --skip-plugin-check

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@dexgate/openclaw-trusted-mode

Links

Acronym Expansions

Quick start (free)

Free vs governed (authorization modes)

What free mode gives you today

What you gain on the full governed path

Quick upgrade (minimal config change)

Free vs governed at a glance

npm Package

ClawHub discovery

What npm install gives you

Authorization paths (reference)

Free / local path

Governed path via decision middleware (preferred)

Need licensed SDE / enterprise?

Licensing

What it does

Free vs Paid

Build and test

Trusted Mode Check

Local install in OpenClaw (WSL)

Plugin config

Compatibility Matrix Automation

Security Gates

Schema Contract and Evidence Bundle

Startup Health Verification

What `npm install` gives you