openclaw-brokerkit 0.1.0 → 0.2.1

package/README.md

@@ -1,16 +1,16 @@
 # OpenClaw BrokerKit
 
-`openclaw-brokerkit` adds a provider-neutral Approvals tab and `/brokerkit`
-commands to OpenClaw. It connects to one or more BrokerKit Operator V1 sources.
-The brokers remain authoritative and retain all provider credentials and
-executable plans.
+`openclaw-brokerkit` is an OpenClaw plugin that adds a provider-neutral
+Approvals tab and `/brokerkit` commands to OpenClaw. It connects to one or
+more BrokerKit Operator V1 sources; the brokers remain authoritative and
+retain all provider credentials and executable plans.
 
-The minimum supported host is `openclaw@2026.7.1-beta.5`, the first published
+The minimum supported host is `openclaw@2026.7.1`, the first stable
 SDK used by this package that includes public tab descriptors.
 
 ## Install
 
-After the package is published, install an exact release from
+Install an exact release from
 [npm](https://www.npmjs.com/package/openclaw-brokerkit) through OpenClaw:
 
 ```sh
@@ -24,15 +24,16 @@ pnpm --filter openclaw-brokerkit build
 openclaw plugins install --link ./plugins/openclaw
 ```
 
-Choose one explicit trust mode:
+## Choose a trust mode
 
-- `direct` trusts the OpenClaw process with operator SecretRefs and enables the
-  tab, background reconciliation, `/brokerkit` commands, and channel delivery.
-- `delegated-web` packages only the tab UI and delegates authenticated browser
-  requests to a same-origin trusted backend. It gives OpenClaw no broker
-  credential and registers no command or background source service.
+- `direct` trusts the OpenClaw process with operator SecretRefs and enables
+  the tab, background reconciliation, `/brokerkit` commands, and channel
+  delivery.
+- `delegated-web` packages only the tab UI and delegates authenticated
+  browser requests to a same-origin trusted backend. It gives OpenClaw no
+  broker credential and registers no command or background source service.
 
-## Configuration
+## Direct mode configuration
 
 ```json5
 {
@@ -46,7 +47,7 @@ Choose one explicit trust mode:
             {
               id: "hf-primary",
               label: "Hugging Face",
-              endpoint: "http://127.0.0.1:18080",
+              endpoint: "https://hf-broker.example.com",
               operatorCredential: {
                 source: "env",
                 provider: "default",
@@ -61,12 +62,34 @@ Choose one explicit trust mode:
 }
 ```
 
-Literal operator credentials are rejected. Non-loopback sources require HTTPS.
-Each `endpoint` is the broker's Operator V1 listener, not its agent listener.
-The plugin stores only cursors, opaque handles, generic channel destinations,
-and delivery bookkeeping under the OpenClaw service state directory.
+Literal operator credentials are rejected; `operatorCredential.source` is
+`env`, `file`, or `exec`. Non-loopback endpoints require HTTPS. Each
+`endpoint` is the broker's Operator V1 listener, not its agent listener. The
+plugin stores only cursors, opaque handles, generic channel destinations, and
+delivery bookkeeping under the OpenClaw service state directory.
 
-For a deployment that treats OpenClaw as untrusted, configure delegated web:
+## Commands
+
+```text
+/brokerkit subscribe
+/brokerkit unsubscribe
+/brokerkit pending
+/brokerkit show <handle>
+/brokerkit approve <handle>
+/brokerkit deny <handle>
+/brokerkit revoke <handle>
+```
+
+Commands are registered only in direct mode. They require an authorized
+sender and the `operator.approvals` scope. Requesters cancel their own
+pending requests through the authenticated broker client API, not through
+this operator surface. Subscriptions use OpenClaw's generic outbound adapter,
+so this package contains no Telegram, Discord, Slack, or other
+channel-specific implementation.
+
+## Delegated web mode
+
+For a deployment that treats OpenClaw as untrusted:
 
 ```json5
 {
@@ -87,111 +110,123 @@ For a deployment that treats OpenClaw as untrusted, configure delegated web:
 ```
 
 The trusted backend implements `brokerkit.io/delegated-web/v1`, authenticates
-the human operator, and issues an in-memory decision token lasting no more than
-five minutes. The base path must be a normalized same-origin absolute path.
-The OpenClaw gateway must set `gateway.controlUi.embedSandbox` to `scripts` so
-the approval tab can run while retaining its opaque sandbox origin. Do not use
-`trusted`; delegated authentication is designed for the stricter scripts-only
-sandbox.
+the human operator, and issues an in-memory decision token lasting no more
+than five minutes. The base path must be a normalized same-origin absolute
+path. The OpenClaw gateway must set `gateway.controlUi.embedSandbox` to
+`scripts` so the approval tab can run while retaining its opaque sandbox
+origin; do not use `trusted`.
 
 When OpenClaw is outside the credential trust boundary, the trusted backend
 must serve the packaged `dist/ui` files at the registered UI path itself. A
-framed popover may receive a server-enforced `read` or `decide` session. A
-`read` session shows requests without action controls. A `decide` session lets
-the operator act directly in the frame. Hosts that use framed decisions accept
-that the surrounding application controls the iframe's placement and can
-attempt UI redressing; use the navigation-only launcher below when that threat
-must remain out of scope.
+framed popover may receive a server-enforced `read` or `decide` session: a
+`read` session shows requests without action controls, and a `decide` session
+lets the operator act directly in the frame. Hosts that use framed decisions
+accept that the surrounding application controls the iframe's placement and
+can attempt UI redressing; use the navigation-only launcher below when that
+threat must remain out of scope.
 
-The host injects the short-lived delegated session into the sandboxed response:
+### Session injection
+
+The host injects the short-lived delegated session into the sandboxed
+response:
 
 ```html
 <meta name="brokerkit-delegated-session" content="BASE64URL_SESSION_JSON" />
 ```
 
-With `access: "read"`, each actionable request renders a **Review securely**
-button instead of decision controls. The button posts this navigation-only
-message:
-
-```text
-{ type: "brokerkit.delegated-web.open", version: 1, nonce }
-```
-
-The host verifies the exact opaque-origin frame source and navigates the whole
-browser tab to the trusted UI URL. The top-level response is unframeable and
-contains a server-enforced decision session, so approval, denial, cancellation,
-and revocation require a second explicit action in the trusted document.
-
-A host that does not provide a framed inbox can inject this marker so the UI
-renders only the secure-navigation launcher:
-
-```html
-<meta name="brokerkit-delegated-top-level" />
-```
+Token-bearing HTML responses must enforce `sandbox allow-scripts` in their
+CSP, and immutable UI assets must be loadable by the opaque document (serve
+them without a same-origin CORP restriction or set
+`Cross-Origin-Resource-Policy: cross-origin`).
 
 The content is a base64url-encoded `brokerkit.io/delegated-web/v1` session
-object. The UI removes the element as soon as it reads it. Version 1 uses this
-closed payload:
+object; the UI removes the element as soon as it reads it. Version 1 uses
+this closed payload:
 
 ```json
 {
   "api_version": "brokerkit.io/delegated-web/v1",
-  "token": "opaque-short-lived-bearer-token",
-  "expires_at": "2026-07-12T13:30:00Z",
+  "token": "opaque-short-lived-browser-session",
+  "expires_at": "<no more than five minutes from issue time, RFC3339>",
   "access": "read",
   "renewal_transport": "direct"
 }
 ```
 
 `access` is `read` or `decide`; the host enforces it on every endpoint.
-`renewal_transport` is `direct` or `parent`. Direct renewal posts to
-`<basePath>/session` with the current token as a bearer credential and omits
-cookies. Parent renewal uses the nonce-bound bridge below. The host preserves
-the token's access when it returns a replacement session.
+`renewal_transport` is `direct` (the UI posts the current session to
+`<basePath>/session`) or `parent` (the nonce-bound bridge below returns the
+replacement session in memory). The host preserves the token's access when it
+returns a replacement session.
 
-When the parent application is trusted, a sandboxed tab that cannot call the
-delegated session endpoint directly may instead use this host-neutral bridge:
+### Browser session transport
 
-```text
-request:  { type: "brokerkit.delegated-web.session.request", version: 1, nonce }
-response: { type: "brokerkit.delegated-web.session.response", nonce, session }
+Every direct and delegated-web browser API call carries its raw session in
+one fixed HTTP field:
+
+```http
+GET /trusted-host/api/brokerkit/snapshot HTTP/1.1
+Origin: null
+BrokerKit-Session: eyJ2ZXJzaW9uIjoxLCJhdWRpZW5jZSI6Ii4uLiJ9.signature
+Accept: application/json
 ```
 
-The trusted parent must answer only requests from the embedded BrokerKit frame
-and must bind each response to the supplied 128-bit nonce. `session` is the
-same `brokerkit.io/delegated-web/v1` object returned by `POST
-<basePath>/session`. The bridge is a BrokerKit interface; it contains no
-host-product namespace or host-specific payload.
+`BrokerKit-Session` has no authentication-scheme prefix. A host must reject
+empty, repeated, combined, malformed, or oversized values; tokens are 32 to
+4096 bytes of visible ASCII excluding comma and whitespace. The same field
+protects `POST /session`, `GET /snapshot`, `GET /events`, request detail,
+approval, denial, and revocation; direct-mode capabilities use it on
+`/plugins/brokerkit/api/v1` as well.
+
+Standard `Authorization` is reserved for the hosting edge and for
+server-to-server Operator V1 clients. Browser clients never use it, and never
+put a delegated session in cookies, query parameters, local storage, or
+session storage. Tokens must not be logged, traced, reflected in errors,
+copied into an Operator V1 request, or persisted by the host or UI.
+
+Because the packaged UI has an opaque origin under the required scripts-only
+sandbox, a delegated host must accept only the expected `Origin: null`,
+return `Access-Control-Allow-Origin: null`, allow `BrokerKit-Session` and
+`Content-Type` in preflight responses, allow only its fixed route methods,
+and set `Vary: Origin` plus `Cache-Control: no-store`. It must not return
+`Access-Control-Allow-Credentials: true`; delegated API requests deliberately
+omit cookies.
+
+### Secure-navigation launcher
 
-## Commands
+With `access: "read"`, each actionable request renders a **Review securely**
+button instead of decision controls. The button posts this navigation-only
+message:
 
 ```text
-/brokerkit subscribe
-/brokerkit unsubscribe
-/brokerkit pending
-/brokerkit show <handle>
-/brokerkit approve <handle>
-/brokerkit deny <handle>
-/brokerkit cancel <handle>
-/brokerkit revoke <handle>
+{ type: "brokerkit.delegated-web.open", version: 1, nonce }
 ```
 
-Commands are registered only in direct mode. They require an authorized sender
-and the `operator.approvals` scope.
-Subscriptions use OpenClaw's generic outbound adapter, so this package contains
-no Telegram, Discord, Slack, or other channel-specific implementation.
+The host verifies the exact opaque-origin frame source and navigates the
+whole browser tab to the trusted UI URL. The top-level response is
+unframeable and contains a server-enforced decision session, so approval,
+denial, and revocation require a second explicit action in the trusted
+document.
 
-## Verify
+A host that does not provide a framed inbox can inject this marker so the UI
+renders only the secure-navigation launcher:
 
-```sh
-pnpm --filter openclaw-brokerkit check
-pnpm --filter openclaw-brokerkit test
-pnpm --filter openclaw-brokerkit test:browser
-pnpm --filter openclaw-brokerkit build
-pnpm --filter openclaw-brokerkit test:package
+```html
+<meta name="brokerkit-delegated-top-level" />
+```
+
+### Parent session bridge
+
+When the parent application is trusted, a sandboxed tab that cannot call the
+delegated session endpoint directly may instead use this host-neutral bridge:
+
+```text
+request:  { type: "brokerkit.delegated-web.session.request", version: 1, nonce }
+response: { type: "brokerkit.delegated-web.session.response", nonce, session }
 ```
 
-The browser suite runs direct and delegated hosting in Chromium, Firefox, and
-WebKit at desktop and mobile sizes. The package test installs the tarball in a
-fresh directory beside the exact minimum OpenClaw release and imports the
-public plugin entry.
+The trusted parent must answer only requests from the embedded BrokerKit
+frame and must bind each response to the supplied 128-bit nonce. `session` is
+the same `brokerkit.io/delegated-web/v1` object returned by
+`POST <basePath>/session`. The bridge is a BrokerKit interface; it contains
+no host-product namespace or host-specific payload.

package/dist/src/browser-session.js

@@ -0,0 +1,7 @@
+export const BROWSER_SESSION_HEADER = "BrokerKit-Session";
+export const MAX_BROWSER_SESSION_BYTES = 4096;
+export function validBrowserSession(value) {
+    return (value.length >= 32 &&
+        value.length <= MAX_BROWSER_SESSION_BYTES &&
+        /^[\x21-\x2B\x2D-\x7E]+$/u.test(value));
+}

package/dist/src/commands.js

@@ -36,8 +36,8 @@ export async function handleCommand(runtime, ctx) {
             return { text: "Invalid BrokerKit command." };
         const lines = runtime
             .snapshot()
-            .requests.filter((request) => request.status === "pending")
-            .map((request) => `${request.handle} · ${request.sourceLabel} · ${request.presentation.title}`);
+            .requests.filter((request) => request.request.status === "pending")
+            .map((request) => `${request.handle} · ${request.source_label} · ${request.request.presentation.title}`);
         return {
             text: lines.length ? lines.join("\n") : "No pending BrokerKit requests.",
         };
@@ -49,13 +49,13 @@ export async function handleCommand(runtime, ctx) {
         .requests.find((item) => item.handle === handle);
     if (command === "show")
         return { text: request ? formatRequest(request) : "Request not found." };
-    if (["approve", "deny", "cancel", "revoke"].includes(command)) {
+    if (["approve", "deny", "revoke"].includes(command)) {
         if (!request)
             return { text: "Request not found." };
         try {
-            const updated = await runtime.decide(handle, command, request.revision, ctx.senderId);
+            const updated = await runtime.decide(handle, command, request.request.revision, ctx.senderId);
             return {
-                text: `${capitalize(command)} committed for ${updated.presentation.title}.`,
+                text: `${capitalize(command)} committed for ${updated.request.presentation.title}.`,
             };
         }
         catch (error) {
@@ -88,11 +88,10 @@ function capitalize(value) {
     return value.charAt(0).toUpperCase() + value.slice(1);
 }
 function formatRequest(request) {
-    const facts = request.presentation.facts?.map((fact) => `${fact.label}: ${fact.value}`) ??
-        [];
+    const facts = request.request.presentation.facts?.map((fact) => `${fact.label}: ${fact.value}`) ?? [];
     return [
-        `${request.sourceLabel}: ${request.presentation.title}`,
-        request.presentation.summary ?? "",
+        `${request.source_label}: ${request.request.presentation.title}`,
+        request.request.presentation.summary ?? "",
         ...facts,
         `Handle: ${request.handle}`,
     ]

package/dist/src/generated/openapi-operator-v1.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/src/generated/operator-v1.js

@@ -1,5 +1,4 @@
-// Generated by scripts/generate-operator-v1.mjs. Do not edit.
-export const OPERATOR_V1_SCHEMA_SHA256 = "a4510c3d0e1ddf32dfb8e8bd684677ade3f3d6541912d42720af8c43ef11c2eb";
+export const OPERATOR_V1_SCHEMA_SHA256 = "62065b7c9d09989c66379c6a81dd23f9ae468c7d1a859b69c88a1dee079aa6a6";
 export const operatorV1 = {
     apiVersion: "brokerkit.io/operator/v1",
     statuses: [
@@ -11,7 +10,7 @@ export const operatorV1 = {
         "consumed",
         "revoked",
     ],
-    actions: ["approve", "deny", "cancel", "revoke"],
+    actions: ["approve", "deny", "revoke"],
     risks: ["unknown", "low", "medium", "high", "critical"],
     eventKinds: [
         "request.created",
@@ -19,21 +18,26 @@ export const operatorV1 = {
         "request.denied",
         "request.canceled",
         "request.expired",
-        "request.consumed",
-        "request.revoked",
-        "request.updated",
+        "grant.revoked",
+        "grant.reserved",
+        "grant.consumed",
+        "grant.released",
+        "execution.succeeded",
+        "execution.failed",
+        "execution.ambiguous",
     ],
     errorCodes: [
         "invalid_request",
         "unauthorized",
         "forbidden",
         "not_found",
+        "method_not_allowed",
         "revision_conflict",
-        "invalid_transition",
-        "constraint_exceeded",
         "idempotency_conflict",
+        "constraint_exceeded",
+        "invalid_transition",
+        "invalid_decision_token",
         "cursor_expired",
-        "rate_limited",
         "temporarily_unavailable",
         "internal_error",
     ],
@@ -52,6 +56,6 @@ export const operatorV1 = {
         page: 100,
         idempotencyKey: 200,
         errorMessage: 500,
-        correlationId: 200,
+        correlationId: 128,
     },
 };