@darkelogix/openclaw-trusted-mode 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -12,6 +12,11 @@ Terminology and acronyms: [`GLOSSARY.md`](./GLOSSARY.md).
 ## Unreleased
 - No unreleased changes recorded.
 
+## v1.0.5
+- Add `openclaw-trusted-mode-configure`, a dedicated guided config writer for governed OpenClaw hosts that updates `~/.openclaw/openclaw.json` with `plugins.allow`, tenant, gateway, environment, PDP URL, and fail-closed settings.
+- Remove the remaining manual-JSON ambiguity from the package docs by documenting the new configure command for governed mode.
+- Keep the package contract explicit by publishing the new configure CLI and its config-writer module in the npm tarball.
+
 ## v1.0.4
 - Make the public npm package install-safe for current OpenClaw builds by separating Trusted Mode Check environment reads from PDP network calls in the shipped CLI entrypoint.
 - Align `openclaw.plugin.json` with the published package version and keep the required helper CLI modules in the npm tarball.

package/README.md

@@ -128,6 +128,19 @@ openclaw plugins info openclaw-trusted-mode
 
 For a standalone free-mode config, start from [`openclaw.user-config.entry.example.json`](./openclaw.user-config.entry.example.json).
 
+For governed mode, install/register the plugin first, then write the OpenClaw host config with:
+
+```bash
+openclaw-trusted-mode-configure \
+  --tenantId darkelogix \
+  --gatewayId gw-dev \
+  --environment dev \
+  --pdpUrl http://10.90.0.6:8001/v1/authorize \
+  --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`](./openclaw.plugin.json) for config schema and defaults, including:
@@ -165,6 +178,8 @@ Recommended paid / PDP-backed baseline:
   "toolPolicyMode": "PDP",
   "pdpUrl": "http://localhost:8001/v1/authorize",
   "tenantId": "trial-tenant",
+  "gatewayId": "gw-smoke-1",
+  "environment": "prod",
   "failClosed": true,
   "certificationStatus": "LOCKDOWN_ONLY"
 }
@@ -198,4 +213,3 @@ npm run bundle-release-evidence
 npm run startup-health-check -- --skip-plugin-check
 ```
 
-

package/SELF_SERVICE_FAQ.md

@@ -54,8 +54,8 @@ If not:
 Set-Location <openclaw-trusted-mode-path>
 npm install
 npm run build
-openclaw plugins install <openclaw-trusted-mode-path> --no-color
-openclaw plugins info openclaw-trusted-mode --no-color
+openclaw plugins install <openclaw-trusted-mode-path>
+openclaw plugins info openclaw-trusted-mode
 ```
 
 Expected: plugin status is `loaded`.
@@ -104,7 +104,24 @@ Check in order:
 3. If using WSL, test `host.docker.internal` endpoint.
 4. Keep `failClosed=true` in production.
 
-## 6) License endpoint or support placeholders are unresolved
+## 6) `[Trusted Mode ERROR] Hardening config invalid`
+
+Meaning: OpenClaw loaded the plugin, but `~/.openclaw/openclaw.json` still has an incomplete plugin config.
+
+For governed mode, rewrite the host config with:
+
+```powershell
+openclaw-trusted-mode-configure --tenantId <tenant-id> --gatewayId <gateway-id> --environment <environment> --pdpUrl http://<guard-pro-host>:8001/v1/authorize --certificationStatus LOCKDOWN_ONLY
+```
+
+That command:
+
+1. Adds `openclaw-trusted-mode` to `plugins.allow`.
+2. Sets `toolPolicyMode=PDP`.
+3. Writes `tenantId`, `gatewayId`, `environment`, `pdpUrl`, `failClosed=true`, and `allowedTenantIds=[tenantId]`.
+4. Replaces stale standalone `ALLOWLIST_ONLY` defaults that can block governed startup.
+
+## 7) License endpoint or support placeholders are unresolved
 
 Define and verify the values from `START_HERE.md` section "Remaining org-specific values to fill once":
 
@@ -117,7 +134,7 @@ After setting values:
 1. Re-run licensing/activation check (`sde-cli license status`).
 2. Re-run pilot or production readiness checklist.
 
-## 7) `ENTITLEMENT_DENIED` for expected active tenant
+## 8) `ENTITLEMENT_DENIED` for expected active tenant
 
 1. Inspect `ops/entitlements.json` for exact tenant key and SKU.
 2. Confirm request `tenant_id` matches exactly.
@@ -129,7 +146,7 @@ Set-Location <sde-enterprise-path>
 python ops\pdp_admin_cli.py authorize-test --tenant-id <tenant_id> --tool-name read_file --gateway-id gw-1 --environment prod
 ```
 
-## 8) Policy pack signature verification errors
+## 9) Policy pack signature verification errors
 
 1. Confirm both files exist for active variant:
 - `<variant>.json`

package/START_HERE.md

@@ -110,13 +110,13 @@ Copy-Item <sde-enterprise-path>\.env.example <sde-enterprise-path>\.env -Force
 
 Use this path if you want practical local hardening without SDE PDP.
 
-```powershell
-Set-Location <openclaw-trusted-mode-path>
-npm install
-npm run build
-openclaw plugins install <openclaw-trusted-mode-path> --no-color
-openclaw plugins info openclaw-trusted-mode --no-color
-```
+```powershell
+Set-Location <openclaw-trusted-mode-path>
+npm install
+npm run build
+openclaw plugins install <openclaw-trusted-mode-path>
+openclaw plugins info openclaw-trusted-mode
+```
 
 Expected: plugin status is `loaded`.
 
@@ -152,15 +152,16 @@ Expected:
 
 ## 6) Build and install plugin for SDE-backed mode
 
-```powershell
-Set-Location <openclaw-trusted-mode-path>
-npm install
-npm run build
-openclaw plugins install <openclaw-trusted-mode-path> --no-color
-openclaw plugins info openclaw-trusted-mode --no-color
-```
-
-Expected: plugin status is `loaded`.
+```powershell
+Set-Location <openclaw-trusted-mode-path>
+npm install
+npm run build
+openclaw plugins install <openclaw-trusted-mode-path>
+openclaw plugins info openclaw-trusted-mode
+openclaw-trusted-mode-configure --tenantId <tenant-id> --gatewayId <gateway-id> --environment <environment> --pdpUrl http://<guard-pro-host>:8001/v1/authorize --certificationStatus LOCKDOWN_ONLY
+```
+
+Expected: plugin status is `loaded`.
 
 ## 7) Run first-success smoke tests
 

package/dist/configureCli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseConfigureCliArgs = parseConfigureCliArgs;
+exports.runConfigureCli = runConfigureCli;
+const node_process_1 = require("node:process");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const openclawConfig_1 = require("./openclawConfig");
+const runtimeCertification_1 = require("./runtimeCertification");
+function printHelp() {
+    console.log(`Configure ${openclawConfig_1.PLUGIN_ID} governed mode in OpenClaw.
+
+Usage:
+  openclaw-trusted-mode-configure --tenantId <tenant> --gatewayId <gateway> --environment <environment> --pdpUrl <url> [options]
+
+Options:
+  --policyVariant <variant>         Policy variant to store in plugin config.
+                                   Default: guard-pro.v2026.02
+  --configPath <path>              OpenClaw config path.
+                                   Default: ${openclawConfig_1.DEFAULT_OPENCLAW_CONFIG_PATH}
+  --certificationStatus <status>   CERTIFIED_ENFORCED | LOCKDOWN_ONLY | UNSUPPORTED
+                                   Default: LOCKDOWN_ONLY
+  --pdpTimeoutMs <ms>              PDP timeout to store in plugin config.
+                                   Default: 5000
+  --failOpen                       Write failClosed=false instead of true.
+  --json                           Print a JSON summary instead of prose.
+  --help                           Show this help text.
+`);
+}
+function expandHomePath(value) {
+    if (value === "~")
+        return (0, node_os_1.homedir)();
+    if (value.startsWith("~/") || value.startsWith("~\\")) {
+        return (0, node_path_1.join)((0, node_os_1.homedir)(), value.slice(2));
+    }
+    return value;
+}
+function readFlagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+function parseConfigureCliArgs(argv) {
+    if (argv.includes("--help")) {
+        printHelp();
+        (0, node_process_1.exit)(0);
+    }
+    const tenantId = readFlagValue(argv, "--tenantId");
+    const gatewayId = readFlagValue(argv, "--gatewayId");
+    const environment = readFlagValue(argv, "--environment");
+    const pdpUrl = readFlagValue(argv, "--pdpUrl");
+    const policyVariant = readFlagValue(argv, "--policyVariant") || "guard-pro.v2026.02";
+    const configPath = expandHomePath(readFlagValue(argv, "--configPath") || (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json"));
+    const certificationStatus = (0, runtimeCertification_1.normalizeRuntimeCertificationStatus)(readFlagValue(argv, "--certificationStatus") || "LOCKDOWN_ONLY");
+    const timeoutRaw = readFlagValue(argv, "--pdpTimeoutMs");
+    const pdpTimeoutMs = timeoutRaw ? Number(timeoutRaw) : 5000;
+    const failClosed = !argv.includes("--failOpen");
+    const jsonMode = argv.includes("--json");
+    const missing = [
+        ["--tenantId", tenantId],
+        ["--gatewayId", gatewayId],
+        ["--environment", environment],
+        ["--pdpUrl", pdpUrl],
+    ].filter(([, value]) => !value);
+    if (missing.length > 0) {
+        throw new Error(`Missing required flags: ${missing.map(([flag]) => flag).join(", ")}`);
+    }
+    if (!Number.isFinite(pdpTimeoutMs) || pdpTimeoutMs <= 0) {
+        throw new Error("--pdpTimeoutMs must be a positive number");
+    }
+    return {
+        tenantId: tenantId,
+        gatewayId: gatewayId,
+        environment: environment,
+        pdpUrl: pdpUrl,
+        policyVariant,
+        configPath,
+        certificationStatus,
+        failClosed,
+        pdpTimeoutMs,
+        jsonMode,
+    };
+}
+function runConfigureCli(argv = process.argv.slice(2)) {
+    try {
+        const options = parseConfigureCliArgs(argv);
+        const result = (0, openclawConfig_1.writeGovernedConfig)(options);
+        const output = {
+            pluginId: openclawConfig_1.PLUGIN_ID,
+            configPath: result.configPath,
+            created: result.created,
+            pluginAllowAdded: result.pluginAllowAdded,
+            mode: "governed",
+            values: {
+                tenantId: options.tenantId,
+                gatewayId: options.gatewayId,
+                environment: options.environment,
+                pdpUrl: options.pdpUrl,
+                policyVariant: options.policyVariant,
+                certificationStatus: options.certificationStatus,
+                failClosed: options.failClosed,
+                pdpTimeoutMs: options.pdpTimeoutMs,
+            },
+        };
+        if (options.jsonMode) {
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        console.log(`Configured ${openclawConfig_1.PLUGIN_ID} governed mode at ${result.configPath}`);
+        console.log(`- plugins.allow includes ${openclawConfig_1.PLUGIN_ID}`);
+        console.log(`- tenantId=${options.tenantId}`);
+        console.log(`- gatewayId=${options.gatewayId}`);
+        console.log(`- environment=${options.environment}`);
+        console.log(`- pdpUrl=${options.pdpUrl}`);
+        console.log(`- toolPolicyMode=PDP`);
+        console.log(`- failClosed=${options.failClosed}`);
+        console.log(`- certificationStatus=${options.certificationStatus}`);
+    }
+    catch (error) {
+        console.error(error.message);
+        console.error(`Run "openclaw-trusted-mode-configure --help" for usage.`);
+        (0, node_process_1.exit)(1);
+    }
+}
+if (require.main === module) {
+    runConfigureCli();
+}

package/dist/openclawConfig.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPENCLAW_CONFIG_PATH = exports.PLUGIN_ID = void 0;
+exports.normalizeConfigText = normalizeConfigText;
+exports.parseOpenClawConfig = parseOpenClawConfig;
+exports.configureGovernedPlugin = configureGovernedPlugin;
+exports.writeGovernedConfig = writeGovernedConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.PLUGIN_ID = "openclaw-trusted-mode";
+exports.DEFAULT_OPENCLAW_CONFIG_PATH = "~/.openclaw/openclaw.json";
+function ensureObject(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function normalizeConfigText(text) {
+    return `${text.trimEnd()}\n`;
+}
+function parseOpenClawConfig(raw) {
+    const parsed = JSON.parse(raw);
+    return ensureObject(parsed);
+}
+function configureGovernedPlugin(baseConfig, input) {
+    const nextConfig = ensureObject(baseConfig);
+    const plugins = ensureObject(nextConfig.plugins);
+    const existingAllow = Array.isArray(plugins.allow) ? [...plugins.allow] : [];
+    const allow = existingAllow.filter((item) => typeof item === "string");
+    const pluginAllowAdded = !allow.includes(exports.PLUGIN_ID);
+    if (pluginAllowAdded) {
+        allow.push(exports.PLUGIN_ID);
+    }
+    const entries = ensureObject(plugins.entries);
+    const existingEntry = ensureObject(entries[exports.PLUGIN_ID]);
+    const existingPluginConfig = ensureObject(existingEntry.config);
+    const nextPluginConfig = {
+        ...existingPluginConfig,
+        pdpUrl: input.pdpUrl,
+        policyVariant: input.policyVariant,
+        pdpTimeoutMs: input.pdpTimeoutMs,
+        failClosed: input.failClosed,
+        tenantId: input.tenantId,
+        gatewayId: input.gatewayId,
+        environment: input.environment,
+        toolPolicyMode: "PDP",
+        requireTenantId: true,
+        allowedTenantIds: [input.tenantId],
+        certificationStatus: input.certificationStatus,
+    };
+    delete nextPluginConfig.allowedTools;
+    entries[exports.PLUGIN_ID] = {
+        ...existingEntry,
+        enabled: true,
+        config: nextPluginConfig,
+    };
+    plugins.allow = allow;
+    plugins.entries = entries;
+    nextConfig.plugins = plugins;
+    return {
+        config: nextConfig,
+        pluginAllowAdded,
+    };
+}
+function writeGovernedConfig(input) {
+    let parsed = {};
+    let created = false;
+    try {
+        parsed = parseOpenClawConfig((0, node_fs_1.readFileSync)(input.configPath, "utf8"));
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            created = true;
+        }
+        else {
+            throw error;
+        }
+    }
+    const { config, pluginAllowAdded } = configureGovernedPlugin(parsed, input);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(input.configPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(input.configPath, normalizeConfigText(JSON.stringify(config, null, 2)), "utf8");
+    return {
+        configPath: input.configPath,
+        created,
+        pluginAllowAdded,
+    };
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-trusted-mode",
   "name": "Trusted Mode Governance",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Provable enforcement using SDE-PDP + signed policy packs",
   "author": "Darkelogix",
   "hooks": ["before_tool_call"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkelogix/openclaw-trusted-mode",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "MIT-licensed OpenClaw Trusted Mode plugin with standalone hardening and optional SDE-backed governance",
   "license": "MIT",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
     ".": "./dist/index.js"
   },
   "bin": {
-    "openclaw-trusted-mode-check": "./dist/cli.js"
+    "openclaw-trusted-mode-check": "./dist/cli.js",
+    "openclaw-trusted-mode-configure": "./dist/configureCli.js"
   },
   "homepage": "https://www.darkelogix.ai/openclaw/",
   "repository": {
@@ -39,10 +40,12 @@
     "dist/cli.js",
     "dist/cliConfig.js",
     "dist/cliPdpClient.js",
+    "dist/configureCli.js",
     "dist/constraints.js",
     "dist/contextCurator.js",
     "dist/hardening.js",
     "dist/index.js",
+    "dist/openclawConfig.js",
     "dist/packageVersion.js",
     "dist/runtimeCertification.js",
     "dist/sdeGuidance.js",
@@ -78,6 +81,7 @@
     "verify-compatibility-matrix": "node scripts/update_compatibility_matrix.js --check",
     "enforce-cert-quota": "node scripts/enforce_cert_quota.js",
     "trusted-mode-check": "node dist/cli.js",
+    "trusted-mode-configure": "node dist/configureCli.js",
     "trusted-mode-check:mock": "node scripts/mock_pdp.js",
     "lint-docs-terminology": "python scripts/lint_docs_terminology.py"
   },