fix(policy): clarify attestation trust boundary

giodl73-repo · giodl73-repo · commit b11c171c80b1 · 2026-05-20T22:18:27.000-07:00
diff --git a/docs/cli/policy.md b/docs/cli/policy.md
@@ -161,6 +161,12 @@ Policy config lives under `plugins.entries.policy.config`.
 Set `plugins.entries.policy.config.enabled` to `false` to disable policy checks
 for a workspace while leaving the plugin installed.
 
+`expectedHash` and `expectedAttestationHash` are enforcement inputs only when
+OpenClaw config is controlled by a trusted operator, gateway, or supervisor. If
+the governed workspace can edit its own OpenClaw config, those values are
+advisory audit locks: they can still detect drift, but they do not by
+themselves create a boundary against that workspace.
+
 Tool metadata requirements are authored in `policy.jsonc` with
 `tools.requireMetadata`, for example `["risk", "sensitivity", "owner"]`.
 
@@ -251,15 +257,18 @@ these form the audit tuple for this policy check.
 
 If a later gateway or supervisor uses policy to block, approve, or annotate a
 runtime action, it should record the attestation hash from the last clean policy
-check. `checkedAt` stays in JSON output for audit logs, but is not part of the
-stable attestation hash.
+check in a config source the governed workspace cannot silently rewrite.
+`checkedAt` stays in JSON output for audit logs, but is not part of the stable
+attestation hash.
 
 Use this lifecycle when accepting policy state:
 
 1. Author or review `policy.jsonc`.
 2. Run `openclaw policy check --json`.
-3. If the result is clean, record `attestation.policy.hash` as `expectedHash`.
-4. Record `attestation.attestationHash` as `expectedAttestationHash`.
+3. If the result is clean, record `attestation.policy.hash` as `expectedHash`
+   in trusted OpenClaw config.
+4. Record `attestation.attestationHash` as `expectedAttestationHash` in trusted
+   OpenClaw config.
 5. Re-run `openclaw doctor --lint` in CI or release gates.
 
 `policy diff` compares two saved `policy check --json` outputs to explain what
@@ -272,9 +281,11 @@ approval requests: policy path/hash, configured expected hash when present, the
 accepted attestation hash when present, the current policy evidence hash, and
 the target tool reference. Gateway approval request, list, and resolve events
 preserve that metadata so supervisors can audit the decision against the policy
-and workspace state that produced it. If the current attestation no longer
-matches `expectedAttestationHash`, the runtime gate fails closed before asking
-for approval and reports both the current and expected attestation hashes.
+and workspace state that produced it. If trusted config supplies
+`expectedAttestationHash` and the current attestation no longer matches it, the
+runtime gate fails closed before asking for approval and reports both the
+current and expected attestation hashes. If the governed workspace owns the
+config value, treat this as drift detection rather than a security boundary.
 
 If policy rules change intentionally, update both accepted hashes from a clean
 check. If workspace settings change intentionally but policy stays the same,
@@ -445,8 +456,8 @@ The runtime gate:
 
 - blocks tool calls if the enabled policy artifact is missing or does not match
   `expectedHash`;
-- blocks tool calls if `expectedAttestationHash` is configured and the current
-  policy evidence no longer matches the accepted clean policy check;
+- blocks tool calls if trusted config supplies `expectedAttestationHash` and the
+  current policy evidence no longer matches the accepted clean policy check;
 - blocks governed tool calls whose required metadata is missing or invalid;
 - asks for approval for governed tools marked `risk:critical` or
   `IRREVERSIBLE_EXTERNAL`;
diff --git a/docs/plugins/reference/policy.md b/docs/plugins/reference/policy.md
@@ -36,8 +36,10 @@ stable attestation hash.
 When `runtimeToolPolicy` is enabled, the Policy plugin registers a trusted tool
 policy that blocks unverifiable governed tool calls and requests approval for
 critical or irreversible governed tools. If `expectedAttestationHash` is
-configured, the same gate fails closed when current policy evidence no longer
-matches the accepted clean policy check.
+configured by a trusted operator, gateway, or supervisor, the same gate fails
+closed when current policy evidence no longer matches the accepted clean policy
+check. If the governed workspace can edit its own OpenClaw config, the hash is
+an advisory audit lock rather than a boundary against that workspace.
 
 Policy findings do not have to be backed by oc-path. Config and workspace
 findings use `oc://` targets only when the system can point to a resolvable
diff --git a/extensions/policy/openclaw.plugin.json b/extensions/policy/openclaw.plugin.json
@@ -30,11 +30,11 @@
       },
       "expectedHash": {
         "type": "string",
-        "description": "Optional sha256 hash for hash-locking the approved policy artifact."
+        "description": "Optional sha256 hash for hash-locking the approved policy artifact from trusted config."
       },
       "expectedAttestationHash": {
         "type": "string",
-        "description": "Optional sha256 hash for the last accepted clean policy check."
+        "description": "Optional sha256 hash for the last accepted clean policy check from trusted config."
       },
       "path": {
         "type": "string",
diff --git a/extensions/policy/src/cli.test.ts b/extensions/policy/src/cli.test.ts
@@ -1,7 +1,6 @@
 import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { clearHealthChecksForTest } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { clearConfigCache } from "openclaw/plugin-sdk/runtime-config-snapshot";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { policyCheckCommand, policyDiffCommand, policyWatchCommand } from "./cli.js";
diff --git a/src/gateway/protocol/schema/plugin-approvals.ts b/src/gateway/protocol/schema/plugin-approvals.ts
@@ -28,7 +28,6 @@ export const PluginApprovalRequestParamsSchema = Type.Object(
     turnSourceTo: Type.Optional(Type.String()),
     turnSourceAccountId: Type.Optional(Type.String()),
     turnSourceThreadId: Type.Optional(Type.Union([Type.String(), Type.Number()])),
-    metadata: Type.Optional(PluginJsonValueSchema),
     timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_PLUGIN_APPROVAL_TIMEOUT_MS })),
     twoPhase: Type.Optional(Type.Boolean()),
   },
diff --git a/src/gateway/server-methods/plugin-approval.ts b/src/gateway/server-methods/plugin-approval.ts
@@ -75,7 +75,6 @@ export function createPluginApprovalHandlers(
         turnSourceTo?: string | null;
         turnSourceAccountId?: string | null;
         turnSourceThreadId?: string | number | null;
-        metadata?: unknown;
         timeoutMs?: number;
         twoPhase?: boolean;
       };
diff --git a/src/infra/plugin-approvals.ts b/src/infra/plugin-approvals.ts
@@ -1,8 +1,5 @@
 import type { ExecApprovalDecision } from "./exec-approvals.js";
-import {
-  policyApprovalMetadataLines,
-  type ApprovalMetadataValue,
-} from "./policy-approval-metadata.js";
+import { policyApprovalMetadataLines } from "./policy-approval-metadata.js";
 
 type PluginApprovalJsonValue =
   | string
@@ -27,7 +24,6 @@ export type PluginApprovalRequestPayload = {
   turnSourceTo?: string | null;
   turnSourceAccountId?: string | null;
   turnSourceThreadId?: string | number | null;
-  metadata?: ApprovalMetadataValue;
 };
 
 export type PluginApprovalRequest = {
