openclaw-brokerkit 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# 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.
+
+The minimum supported host is `openclaw@2026.7.1-beta.5`, the first published
+SDK used by this package that includes public tab descriptors.
+
+## Install
+
+After the package is published, install an exact release from
+[npm](https://www.npmjs.com/package/openclaw-brokerkit) through OpenClaw:
+
+```sh
+openclaw plugins install npm:openclaw-brokerkit@<version>
+```
+
+For a local monorepo checkout, build and link the package explicitly:
+
+```sh
+pnpm --filter openclaw-brokerkit build
+openclaw plugins install --link ./plugins/openclaw
+```
+
+Choose one explicit 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.
+
+## Configuration
+
+```json5
+{
+  plugins: {
+    entries: {
+      brokerkit: {
+        enabled: true,
+        config: {
+          mode: "direct",
+          brokers: [
+            {
+              id: "hf-primary",
+              label: "Hugging Face",
+              endpoint: "http://127.0.0.1:18080",
+              operatorCredential: {
+                source: "env",
+                provider: "default",
+                id: "HF_BROKER_OPERATOR_SECRET",
+              },
+            },
+          ],
+        },
+      },
+    },
+  },
+}
+```
+
+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.
+
+For a deployment that treats OpenClaw as untrusted, configure delegated web:
+
+```json5
+{
+  plugins: {
+    entries: {
+      brokerkit: {
+        enabled: true,
+        config: {
+          mode: "delegated-web",
+          delegatedWeb: {
+            basePath: "/trusted-host/api/brokerkit",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+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.
+
+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.
+
+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" />
+```
+
+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:
+
+```json
+{
+  "api_version": "brokerkit.io/delegated-web/v1",
+  "token": "opaque-short-lived-bearer-token",
+  "expires_at": "2026-07-12T13:30:00Z",
+  "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.
+
+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 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.
+
+## Commands
+
+```text
+/brokerkit subscribe
+/brokerkit unsubscribe
+/brokerkit pending
+/brokerkit show <handle>
+/brokerkit approve <handle>
+/brokerkit deny <handle>
+/brokerkit cancel <handle>
+/brokerkit revoke <handle>
+```
+
+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.
+
+## Verify
+
+```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
+```
+
+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.

package/dist/index.js

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import { definePluginEntry, } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveConfiguredSecretInputString } from "openclaw/plugin-sdk/secret-input-runtime";
+import { handleCommand } from "./src/commands.js";
+import { parseConfig } from "./src/config.js";
+import { createHttpHandler } from "./src/http.js";
+import { BrokerRuntime } from "./src/runtime.js";
+const configSchema = { parse: parseConfig };
+export function registerBrokerKit(api) {
+    const config = parseConfig(api.pluginConfig);
+    const capability = config.mode === "direct"
+        ? randomBytes(32).toString("base64url")
+        : undefined;
+    const bootstrap = config.mode === "direct"
+        ? {
+            version: 1,
+            mode: "direct",
+            capability: requiredCapability(capability),
+        }
+        : {
+            version: 1,
+            mode: "delegated-web",
+            basePath: config.delegatedWeb.basePath,
+        };
+    let runtime;
+    const requireRuntime = () => {
+        if (!runtime)
+            throw new Error("BrokerKit runtime is not running");
+        return runtime;
+    };
+    api.session.controls.registerControlUiDescriptor({
+        surface: "tab",
+        id: "brokerkit",
+        label: "Approvals",
+        description: "Review pending BrokerKit requests.",
+        icon: "shield-check",
+        group: "control",
+        requiredScopes: ["operator.approvals"],
+        path: `/plugins/brokerkit/ui/#${encodeUiBootstrap(bootstrap)}`,
+    });
+    if (config.mode === "direct") {
+        api.registerService({
+            id: "brokerkit",
+            start: async (ctx) => {
+                runtime = new BrokerRuntime(config, {
+                    resolveCredential: (source) => resolveCredential(api, source),
+                    deliver: async (subscription, text) => {
+                        const adapter = await api.runtime.channel.outbound.loadAdapter(subscription.channel);
+                        if (!adapter?.sendText)
+                            throw new Error("channel does not support text delivery");
+                        await adapter.sendText({
+                            cfg: api.config,
+                            to: subscription.target,
+                            text,
+                            ...(subscription.accountId
+                                ? { accountId: subscription.accountId }
+                                : {}),
+                            ...(subscription.threadId
+                                ? { threadId: subscription.threadId }
+                                : {}),
+                        });
+                    },
+                    log: (level, message) => api.logger[level]?.(message),
+                });
+                await runtime.start(ctx.stateDir);
+            },
+            stop: async () => {
+                await runtime?.stop();
+                runtime = undefined;
+            },
+        });
+        api.registerCommand({
+            name: "brokerkit",
+            description: "Review and decide BrokerKit approval requests.",
+            acceptsArgs: true,
+            requireAuth: true,
+            requiredScopes: ["operator.approvals"],
+            handler: (ctx) => handleCommand(requireRuntime(), ctx),
+        });
+    }
+    api.registerHttpRoute({
+        path: "/plugins/brokerkit",
+        auth: "plugin",
+        match: "prefix",
+        handler: createHttpHandler(config.mode === "direct" ? requireRuntime : undefined, api.rootDir ?? process.cwd(), capability),
+    });
+}
+function encodeUiBootstrap(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+function requiredCapability(value) {
+    if (!value)
+        throw new Error("BrokerKit UI capability was not initialized");
+    return value;
+}
+async function resolveCredential(api, source) {
+    const resolved = await resolveConfiguredSecretInputString({
+        config: api.config,
+        env: process.env,
+        value: source.operatorCredential,
+        path: `plugins.entries.brokerkit.config.brokers.${source.id}.operatorCredential`,
+    });
+    if (!resolved.value)
+        throw new Error(`operator credential unavailable for ${source.id}`);
+    return resolved.value;
+}
+export default definePluginEntry({
+    id: "brokerkit",
+    name: "BrokerKit",
+    description: "Provider-neutral BrokerKit approvals",
+    configSchema,
+    register: registerBrokerKit,
+});

package/dist/src/client.js

@@ -0,0 +1,152 @@
+import { parseBrokerEvent, parseDescriptor, parseErrorEnvelope, parseHealth, parseRequest, parseRequestPage, } from "./operator-v1.js";
+const MAX_JSON_BYTES = 2_000_000;
+const MAX_SSE_FRAME_BYTES = 256_000;
+export class BrokerError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export class BrokerClient {
+    endpoint;
+    credential;
+    timeoutMs;
+    constructor(endpoint, credential, timeoutMs) {
+        this.endpoint = endpoint;
+        this.credential = credential;
+        this.timeoutMs = timeoutMs;
+    }
+    async discover() {
+        const value = parseDescriptor(await this.json("/.well-known/brokerkit-operator"));
+        if (value.api_version !== "brokerkit.io/operator/v1")
+            throw new Error(`unsupported BrokerKit API ${value.api_version}`);
+    }
+    async health() {
+        parseHealth(await this.json("/healthz", {}, false));
+    }
+    async list(status = "pending", cursor) {
+        return parseRequestPage(await this.json(`/api/operator/v1/requests?status=${status}&limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`));
+    }
+    async get(id) {
+        return parseRequest(await this.json(`/api/operator/v1/requests/${encodeURIComponent(id)}`));
+    }
+    decide(id, action, decision) {
+        return this.json(`/api/operator/v1/requests/${encodeURIComponent(id)}/${action}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(decision),
+        }).then(parseRequest);
+    }
+    async *events(cursor, signal) {
+        const response = await this.request(`/api/operator/v1/events${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`, { headers: { accept: "text/event-stream" }, signal });
+        if (!response.ok || !response.body)
+            throw await this.error(response);
+        const reader = response.body
+            .pipeThrough(new TextDecoderStream())
+            .getReader();
+        let buffer = "";
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                return;
+            buffer += chunk.value;
+            if (Buffer.byteLength(buffer, "utf8") > MAX_SSE_FRAME_BYTES)
+                throw new Error("BrokerKit event frame is too large");
+            buffer = buffer.replaceAll("\r\n", "\n");
+            for (;;) {
+                const boundary = buffer.indexOf("\n\n");
+                if (boundary < 0)
+                    break;
+                const frame = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const id = frame
+                    .split("\n")
+                    .find((line) => line.startsWith("id:"))
+                    ?.slice(3)
+                    .trim();
+                const data = frame
+                    .split("\n")
+                    .filter((line) => line.startsWith("data:"))
+                    .map((line) => line.slice(5).trimStart())
+                    .join("\n");
+                if (!data)
+                    continue;
+                const event = parseBrokerEvent(JSON.parse(data));
+                if (!id || event.cursor !== id)
+                    throw new Error("BrokerKit event cursor mismatch");
+                yield event;
+            }
+        }
+    }
+    async json(path, init = {}, authenticated = true) {
+        const response = await this.request(path, init, authenticated);
+        if (!response.ok)
+            throw await this.error(response);
+        requireJSON(response);
+        return JSON.parse(await boundedText(response, MAX_JSON_BYTES));
+    }
+    async request(path, init = {}, authenticated = true) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const signal = init.signal
+            ? AbortSignal.any([init.signal, controller.signal])
+            : controller.signal;
+        try {
+            const headers = new Headers(init.headers);
+            if (authenticated)
+                headers.set("authorization", `Bearer ${await this.credential()}`);
+            return await fetch(new URL(path, this.endpoint), {
+                ...init,
+                headers,
+                signal,
+                redirect: "error",
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async error(response) {
+        try {
+            requireJSON(response);
+            const value = parseErrorEnvelope(JSON.parse(await boundedText(response, 64_000)));
+            return new BrokerError(value?.error.code ?? "internal_error", value?.error.message ?? "BrokerKit request failed", response.status);
+        }
+        catch {
+            return new BrokerError("internal_error", "BrokerKit request failed", response.status);
+        }
+    }
+}
+function requireJSON(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!/^application\/json(?:\s*;|$)/iu.test(contentType))
+        throw new Error("BrokerKit returned an invalid content type");
+}
+async function boundedText(response, limit) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > limit) {
+            await reader.cancel();
+            throw new Error("BrokerKit response is too large");
+        }
+        chunks.push(value);
+    }
+    const joined = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(joined);
+}

package/dist/src/commands.js

@@ -0,0 +1,101 @@
+import { pluginErrorCode } from "./errors.js";
+export async function handleCommand(runtime, ctx) {
+    if (!ctx.isAuthorizedSender || !ctx.senderId)
+        return { text: "Not authorized." };
+    const tokens = (ctx.args ?? "").trim().split(/\s+/).filter(Boolean);
+    const command = tokens[0] ?? "pending";
+    const handle = tokens[1];
+    if (command === "subscribe" || command === "unsubscribe") {
+        if (tokens.length !== 1)
+            return { text: "Invalid BrokerKit command." };
+        if (!validRouting(ctx.channel, ctx.to, ctx.accountId, ctx.messageThreadId))
+            return { text: "This conversation has no stable delivery target." };
+        const value = {
+            channel: ctx.channel,
+            target: ctx.to,
+            ...(ctx.accountId ? { accountId: ctx.accountId } : {}),
+            ...(ctx.messageThreadId !== undefined
+                ? { threadId: String(ctx.messageThreadId) }
+                : {}),
+        };
+        if (command === "subscribe") {
+            const subscription = runtime.subscribe(value);
+            return {
+                text: `Subscribed this conversation (${subscription.id.slice(0, 8)}).`,
+            };
+        }
+        const removed = runtime.unsubscribe(value);
+        return {
+            text: removed
+                ? "Unsubscribed this conversation."
+                : "This conversation was not subscribed.",
+        };
+    }
+    if (command === "pending") {
+        if (tokens.length > 1)
+            return { text: "Invalid BrokerKit command." };
+        const lines = runtime
+            .snapshot()
+            .requests.filter((request) => request.status === "pending")
+            .map((request) => `${request.handle} · ${request.sourceLabel} · ${request.presentation.title}`);
+        return {
+            text: lines.length ? lines.join("\n") : "No pending BrokerKit requests.",
+        };
+    }
+    if (!handle || tokens.length !== 2)
+        return { text: "A single request handle is required." };
+    const request = runtime
+        .snapshot()
+        .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 (!request)
+            return { text: "Request not found." };
+        try {
+            const updated = await runtime.decide(handle, command, request.revision, ctx.senderId);
+            return {
+                text: `${capitalize(command)} committed for ${updated.presentation.title}.`,
+            };
+        }
+        catch (error) {
+            return { text: commandError(error) };
+        }
+    }
+    return { text: "Unknown BrokerKit command." };
+}
+function validRouting(channel, target, accountId, threadId) {
+    return Boolean(channel &&
+        channel.length <= 128 &&
+        target &&
+        target.length <= 4096 &&
+        (!accountId || accountId.length <= 512) &&
+        (threadId === undefined || String(threadId).length <= 512));
+}
+function commandError(error) {
+    const code = pluginErrorCode(error);
+    if (code === "revision_stale")
+        return "This request changed. Review it again before deciding.";
+    if (code === "request_not_found" || code === "request_terminal")
+        return "This request is no longer actionable.";
+    if (code === "action_not_allowed")
+        return "That action is not allowed for this request.";
+    if (code === "source_unavailable")
+        return "The approval source is unavailable. No decision was reported.";
+    return "The decision could not be confirmed. No success was reported.";
+}
+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}`) ??
+        [];
+    return [
+        `${request.sourceLabel}: ${request.presentation.title}`,
+        request.presentation.summary ?? "",
+        ...facts,
+        `Handle: ${request.handle}`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/src/config.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+const secretRef = z
+    .object({
+    source: z.enum(["env", "file", "exec"]),
+    provider: z.string().min(1).max(64),
+    id: z.string().min(1).max(512),
+})
+    .strict();
+const broker = z
+    .object({
+    id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+    label: z.string().trim().min(1).max(80),
+    endpoint: z.url(),
+    operatorCredential: secretRef,
+    requestTimeoutMs: z.number().int().min(1000).max(60000).default(10000),
+})
+    .strict();
+const directConfig = z
+    .object({
+    mode: z.literal("direct"),
+    brokers: z.array(broker).min(1).max(32),
+    pollIntervalMs: z.number().int().min(5000).max(300000).default(30000),
+    notificationConcurrency: z.number().int().min(1).max(16).default(4),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const seen = new Set();
+    for (const [index, source] of value.brokers.entries()) {
+        if (seen.has(source.id))
+            ctx.addIssue({
+                code: "custom",
+                path: ["brokers", index, "id"],
+                message: "broker ids must be unique",
+            });
+        seen.add(source.id);
+        const endpoint = new URL(source.endpoint);
+        if (endpoint.username ||
+            endpoint.password ||
+            endpoint.search ||
+            endpoint.hash ||
+            !["http:", "https:"].includes(endpoint.protocol))
+            ctx.addIssue({
+                code: "custom",
+                path: ["brokers", index, "endpoint"],
+                message: "endpoint must be a credential-free HTTP URL",
+            });
+        if (endpoint.protocol === "http:" &&
+            !["127.0.0.1", "localhost", "::1"].includes(endpoint.hostname))
+            ctx.addIssue({
+                code: "custom",
+                path: ["brokers", index, "endpoint"],
+                message: "plaintext HTTP is limited to loopback",
+            });
+    }
+});
+const delegatedWebConfig = z
+    .object({
+    mode: z.literal("delegated-web"),
+    delegatedWeb: z
+        .object({
+        basePath: z.string().superRefine((value, ctx) => {
+            if (!validDelegatedBasePath(value)) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "delegated web basePath must be a normalized same-origin absolute path",
+                });
+            }
+        }),
+    })
+        .strict(),
+})
+    .strict();
+export const configSchema = z.discriminatedUnion("mode", [
+    directConfig,
+    delegatedWebConfig,
+]);
+export function parseConfig(value) {
+    return configSchema.parse(value);
+}
+function validDelegatedBasePath(value) {
+    if (value.length < 2 ||
+        value.length > 256 ||
+        !value.startsWith("/") ||
+        value.startsWith("//") ||
+        value.endsWith("/") ||
+        /[?#\\]/u.test(value) ||
+        hasControlCharacter(value)) {
+        return false;
+    }
+    try {
+        const decoded = decodeURIComponent(value);
+        if (decoded !== value || decoded.includes("..") || decoded.includes("\\")) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    return value
+        .split("/")
+        .every((segment, index) => index === 0 || /^[A-Za-z0-9._~-]+$/u.test(segment));
+}
+function hasControlCharacter(value) {
+    return [...value].some((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code < 32 || code === 127;
+    });
+}

package/dist/src/errors.js

@@ -0,0 +1,15 @@
+import { BrokerError } from "./client.js";
+export function pluginErrorCode(error) {
+    const code = error instanceof BrokerError
+        ? error.code
+        : error instanceof Error
+            ? error.message
+            : "internal_error";
+    if (code === "revision_conflict")
+        return "revision_stale";
+    if (code === "not_found")
+        return "request_not_found";
+    if (code === "invalid_transition" || code === "constraint_exceeded")
+        return "action_not_allowed";
+    return code;
+}