openclaw-brokerkit 0.1.0 → 0.3.0

package/dist/src/http.js

@@ -2,6 +2,7 @@ import { timingSafeEqual } from "node:crypto";
 import { createReadStream, existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { pluginErrorCode } from "./errors.js";
+import { BROWSER_SESSION_HEADER, validBrowserSession, } from "./browser-session.js";
 export function createHttpHandler(runtime, rootDir, capability) {
     const uiDir = path.join(rootDir, "dist", "ui");
     const rateLimit = createRateLimiter(120, 60_000);
@@ -15,18 +16,44 @@ export function createHttpHandler(runtime, rootDir, capability) {
 async function handleApi(req, res, url, runtime, capability, rateLimit) {
     if (!runtime || !capability)
         return json(res, 404, { error: { code: "not_found" } });
-    if (!authorized(req.headers.authorization, capability))
-        return json(res, 401, { error: { code: "not_authorized" } });
     if (req.headers.origin !== "null")
         return json(res, 403, { error: { code: "not_authorized" } });
-    if (url.search)
-        return json(res, 400, { error: { code: "invalid_input" } });
+    if (req.method === "OPTIONS")
+        return preflight(req, res);
+    corsHeaders(res);
+    if (!authorized(browserSession(req), capability))
+        return json(res, 401, { error: { code: "not_authorized" } });
     if (!rateLimit(req.socket.remoteAddress ?? "local"))
         return json(res, 429, { error: { code: "rate_limited" } });
     try {
+        if (req.method === "GET" &&
+            url.pathname === "/plugins/brokerkit/api/v1/events") {
+            const input = parseEventQuery(url);
+            const controller = new AbortController();
+            const close = () => controller.abort();
+            res.once("close", close);
+            try {
+                return json(res, 200, await runtime().waitForSnapshot(input.cursor, input.waitSeconds, controller.signal));
+            }
+            finally {
+                res.off("close", close);
+            }
+        }
+        if (url.search)
+            return json(res, 400, { error: { code: "invalid_input" } });
         if (req.method === "GET" &&
             url.pathname === "/plugins/brokerkit/api/v1/snapshot")
             return json(res, 200, runtime().snapshot());
+        if (req.method === "GET" &&
+            url.pathname === "/plugins/brokerkit/api/v1/summary") {
+            const snapshot = runtime().snapshot();
+            return json(res, 200, {
+                api_version: snapshot.api_version,
+                cursor: snapshot.cursor,
+                pending: snapshot.requests.filter((request) => request.request.status === "pending").length,
+                healthy: snapshot.sources.every((source) => source.healthy),
+            });
+        }
         const detail = url.pathname.match(/^\/plugins\/brokerkit\/api\/v1\/requests\/([^/]+)$/);
         if (req.method === "GET" && detail) {
             const handle = decodeHandle(detail[1]);
@@ -37,7 +64,7 @@ async function handleApi(req, res, url, runtime, capability, rateLimit) {
                 ? json(res, 200, request)
                 : json(res, 404, { error: { code: "request_not_found" } });
         }
-        const decision = url.pathname.match(/^\/plugins\/brokerkit\/api\/v1\/requests\/([^/]+)\/(approve|deny|cancel|revoke)$/);
+        const decision = url.pathname.match(/^\/plugins\/brokerkit\/api\/v1\/requests\/([^/]+)\/(approve|deny|revoke)$/);
         if (req.method === "POST" && decision) {
             if (!isJSON(req.headers["content-type"]))
                 throw new Error("invalid_input");
@@ -70,15 +97,55 @@ function serveUi(req, res, url, uiDir) {
         : "public, max-age=31536000, immutable");
     res.setHeader("content-security-policy", "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; frame-ancestors 'self'");
     securityHeaders(res);
+    if (!file.endsWith("index.html")) {
+        res.setHeader("cross-origin-resource-policy", "cross-origin");
+    }
     createReadStream(file).pipe(res);
     return true;
 }
-function authorized(header, capability) {
-    const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
-    const left = Buffer.from(token);
+function authorized(token, capability) {
+    const left = Buffer.from(token ?? "");
     const right = Buffer.from(capability);
     return left.length === right.length && timingSafeEqual(left, right);
 }
+function browserSession(req) {
+    const values = [];
+    for (let index = 0; index < req.rawHeaders.length; index += 2) {
+        if (req.rawHeaders[index]?.toLowerCase() ===
+            BROWSER_SESSION_HEADER.toLowerCase())
+            values.push(req.rawHeaders[index + 1] ?? "");
+    }
+    if (values.length !== 1 || !validBrowserSession(values[0] ?? ""))
+        return undefined;
+    return values[0];
+}
+function preflight(req, res) {
+    const method = req.headers["access-control-request-method"];
+    const requested = String(req.headers["access-control-request-headers"] ?? "")
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean);
+    const allowedHeaders = new Set([
+        BROWSER_SESSION_HEADER.toLowerCase(),
+        "content-type",
+    ]);
+    if ((method !== "GET" && method !== "POST") ||
+        requested.length === 0 ||
+        requested.some((value) => !allowedHeaders.has(value)))
+        return json(res, 403, { error: { code: "not_authorized" } });
+    res.statusCode = 204;
+    corsHeaders(res);
+    res.setHeader("access-control-allow-methods", "GET, POST");
+    res.setHeader("access-control-allow-headers", `${BROWSER_SESSION_HEADER}, Content-Type`);
+    res.setHeader("cache-control", "no-store");
+    securityHeaders(res);
+    res.end();
+    return true;
+}
+function corsHeaders(res) {
+    res.setHeader("access-control-allow-origin", "null");
+    res.setHeader("vary", "Origin");
+}
 async function readJSON(req) {
     const chunks = [];
     let size = 0;
@@ -218,29 +285,36 @@ function mapHttpError(error) {
         return { code, status: 409 };
     if (code === "action_not_allowed")
         return { code, status: 422 };
+    if (code === "cursor_expired")
+        return { code, status: 410 };
     if (code === "source_unavailable")
         return { code, status: 503 };
     return { code: "internal_error", status: 500 };
 }
+function parseEventQuery(url) {
+    if ([...url.searchParams.keys()].some((key) => !["cursor", "wait_seconds"].includes(key)))
+        throw new Error("invalid_input");
+    const cursor = url.searchParams.get("cursor") ?? "";
+    const wait = url.searchParams.get("wait_seconds") ?? "25";
+    if (cursor.length < 1 ||
+        cursor.length > 128 ||
+        !/^[A-Za-z0-9_.-]+$/u.test(cursor) ||
+        !/^(?:[1-9]|1[0-9]|2[0-5])$/u.test(wait))
+        throw new Error("invalid_input");
+    return { cursor, waitSeconds: Number(wait) };
+}
 function parseDecisionInput(body, action) {
-    if (Object.keys(body).some((key) => key !== "expectedRevision" && key !== "reason" && key !== "constraints") ||
-        !positiveSafeInteger(body.expectedRevision) ||
-        (body.reason !== undefined && typeof body.reason !== "string"))
+    if (Object.keys(body).some((key) => key !== "expectedRevision" && key !== "constraints") ||
+        !positiveSafeInteger(body.expectedRevision))
         throw new Error("invalid_input");
     const options = {};
-    if (typeof body.reason === "string" && body.reason.trim()) {
-        const reason = body.reason.trim();
-        if (Buffer.byteLength(reason, "utf8") > 2000)
-            throw new Error("invalid_input");
-        options.reason = reason;
-    }
     if (body.constraints !== undefined) {
         if (action !== "approve" || !record(body.constraints))
             throw new Error("invalid_input");
         const constraints = body.constraints;
         if (Object.keys(constraints).some((key) => key !== "durationSeconds" && key !== "maxUses") ||
             !positiveSafeInteger(constraints.durationSeconds) ||
-            !positiveSafeInteger(constraints.maxUses))
+            !(constraints.maxUses === null || positiveSafeInteger(constraints.maxUses)))
             throw new Error("invalid_input");
         options.constraints = {
             duration_seconds: constraints.durationSeconds,

package/dist/src/operator-v1.js

@@ -1,92 +1,38 @@
-import { z } from "zod";
-import { operatorV1 } from "./generated/operator-v1.js";
-const timestamp = z.iso.datetime({ offset: true });
-const nonNegativeInteger = z.number().int().nonnegative().safe();
-const positiveInteger = z.number().int().positive().safe();
-const status = z.enum(operatorV1.statuses);
-const action = z.enum(operatorV1.actions);
-const fact = z.object({
-    label: z.string().min(1).max(operatorV1.limits.factLabel),
-    value: z.string().min(1).max(operatorV1.limits.factValue),
-});
-const presentation = z.object({
-    risk: z.enum(operatorV1.risks),
-    title: z.string().min(1).max(operatorV1.limits.title),
-    summary: z.string().max(operatorV1.limits.summary).optional(),
-    facts: z.array(fact).max(operatorV1.limits.facts).optional(),
-});
-export const brokerRequestSchema = z.object({
-    id: z.string().min(1).max(operatorV1.limits.id),
-    revision: positiveInteger,
-    requester: z.string().min(1).max(operatorV1.limits.requester),
-    operation: z.string().min(1).max(operatorV1.limits.operation),
-    status,
-    requested_at: timestamp,
-    pending_expires_at: timestamp.optional(),
-    active_expires_at: timestamp.optional(),
-    requested_duration_seconds: positiveInteger,
-    requested_max_uses: positiveInteger,
-    granted_max_uses: positiveInteger.nullable(),
-    used_count: nonNegativeInteger,
-    request_reason: z.string().max(operatorV1.limits.reason).optional(),
-    decided_at: timestamp.optional(),
-    decided_by: z.string().max(operatorV1.limits.actor).optional(),
-    decided_on_behalf_of: z.string().max(operatorV1.limits.actor).optional(),
-    decision_reason: z.string().max(operatorV1.limits.reason).optional(),
-    presentation,
-    presentation_unavailable: z.boolean().optional(),
-    allowed_actions: z
-        .array(action)
-        .max(operatorV1.actions.length)
-        .refine((value) => new Set(value).size === value.length),
-    approval_bounds: z
-        .object({
-        max_duration_seconds: nonNegativeInteger,
-        max_uses: positiveInteger,
-    })
-        .optional(),
-});
-const requestPageSchema = z.object({
-    requests: z.array(brokerRequestSchema).max(operatorV1.limits.page),
-    next_cursor: z.string().min(1).max(operatorV1.limits.cursor).optional(),
-    event_cursor: z.string().min(1).max(operatorV1.limits.cursor).optional(),
-});
-const brokerEventSchema = z.object({
-    cursor: z.string().min(1).max(operatorV1.limits.cursor),
-    kind: z.enum(operatorV1.eventKinds),
-    request_id: z.string().min(1).max(operatorV1.limits.id),
-    revision: positiveInteger,
-    status,
-    occurred_at: timestamp,
-    used_count: nonNegativeInteger,
-});
-const descriptorSchema = z.object({
-    api_version: z.literal(operatorV1.apiVersion),
-});
-const healthSchema = z.object({ status: z.string().min(1).max(128) });
-const errorEnvelopeSchema = z.object({
-    error: z.object({
-        code: z.enum(operatorV1.errorCodes),
-        message: z.string().min(1).max(operatorV1.limits.errorMessage),
-        correlation_id: z.string().min(1).max(operatorV1.limits.correlationId),
-    }),
-});
+import { validateBrokerEvent, validateBrokerRequest, validateDescriptor, validateErrorEnvelope, validateHealth, validateRequestPage, validateUIRequest, validateUISnapshot, validateUISnapshotEvent, validateUISummary, } from "./generated/operator-validators.js";
 export function parseDescriptor(value) {
-    return descriptorSchema.parse(value);
+    return validated(validateDescriptor, value);
 }
 export function parseHealth(value) {
-    return healthSchema.parse(value);
+    return validated(validateHealth, value);
 }
 export function parseRequest(value) {
-    return brokerRequestSchema.parse(value);
+    return validated(validateBrokerRequest, value);
 }
 export function parseRequestPage(value) {
-    return requestPageSchema.parse(value);
+    return validated(validateRequestPage, value);
 }
 export function parseBrokerEvent(value) {
-    return brokerEventSchema.parse(value);
+    return validated(validateBrokerEvent, value);
+}
+export function parseUIRequest(value) {
+    return validated(validateUIRequest, value);
+}
+export function parseUISnapshot(value) {
+    return validated(validateUISnapshot, value);
+}
+export function parseUISnapshotEvent(value) {
+    return validated(validateUISnapshotEvent, value);
+}
+export function parseUISummary(value) {
+    return validated(validateUISummary, value);
 }
 export function parseErrorEnvelope(value) {
-    const result = errorEnvelopeSchema.safeParse(value);
-    return result.success ? result.data : undefined;
+    return validateErrorEnvelope(value)
+        ? value
+        : undefined;
+}
+function validated(validate, value) {
+    if (!validate(value))
+        throw new Error("Operator V1 response is invalid");
+    return value;
 }

package/dist/src/revisions.js

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+export class RevisionPublisher {
+    epoch;
+    revision = 0;
+    material = "";
+    current;
+    waiters = new Set();
+    constructor(epoch = randomBytes(16).toString("base64url")) {
+        if (!/^[A-Za-z0-9_-]{22}$/u.test(epoch))
+            throw new Error("invalid revision epoch");
+        this.epoch = epoch;
+    }
+    publish(value) {
+        const material = JSON.stringify(value);
+        if (this.current && material === this.material)
+            return this.current;
+        this.material = material;
+        this.revision += 1;
+        this.current = {
+            api_version: "brokerkit.io/operator-ui/v1",
+            cursor: this.cursor(),
+            synchronized_at: new Date().toISOString(),
+            ...value,
+        };
+        for (const waiter of [...this.waiters])
+            this.finish(waiter, {
+                api_version: "brokerkit.io/operator-ui/v1",
+                cursor: this.current.cursor,
+                changed: true,
+            });
+        return this.current;
+    }
+    snapshot() {
+        if (!this.current)
+            throw new Error("source_unavailable");
+        return this.current;
+    }
+    wait(cursor, waitSeconds, signal) {
+        const observed = this.parseCursor(cursor);
+        if (observed === undefined)
+            return Promise.reject(cursorExpired());
+        if (observed !== this.revision)
+            return Promise.resolve({
+                api_version: "brokerkit.io/operator-ui/v1",
+                cursor: this.cursor(),
+                changed: true,
+            });
+        if (signal?.aborted)
+            return Promise.reject(aborted());
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.finish(waiter, {
+                        api_version: "brokerkit.io/operator-ui/v1",
+                        cursor: this.cursor(),
+                        changed: false,
+                    });
+                }, waitSeconds * 1000),
+                ...(signal ? { signal } : {}),
+            };
+            waiter.timer.unref();
+            if (signal) {
+                waiter.abort = () => this.fail(waiter, aborted());
+                signal.addEventListener("abort", waiter.abort, { once: true });
+            }
+            this.waiters.add(waiter);
+        });
+    }
+    close() {
+        for (const waiter of [...this.waiters])
+            this.fail(waiter, new Error("source_unavailable"));
+    }
+    cursor() {
+        return `${this.epoch}.${this.revision.toString(36)}`;
+    }
+    parseCursor(value) {
+        const match = /^([A-Za-z0-9_-]{22})\.([0-9a-z]{1,13})$/u.exec(value);
+        if (!match || match[1] !== this.epoch)
+            return undefined;
+        const revision = Number.parseInt(match[2] ?? "", 36);
+        return Number.isSafeInteger(revision) && revision <= this.revision
+            ? revision
+            : undefined;
+    }
+    finish(waiter, value) {
+        this.cleanup(waiter);
+        waiter.resolve(value);
+    }
+    fail(waiter, error) {
+        this.cleanup(waiter);
+        waiter.reject(error);
+    }
+    cleanup(waiter) {
+        if (!this.waiters.delete(waiter))
+            return;
+        clearTimeout(waiter.timer);
+        if (waiter.signal && waiter.abort)
+            waiter.signal.removeEventListener("abort", waiter.abort);
+    }
+}
+function cursorExpired() {
+    return Object.assign(new Error("cursor_expired"), { code: "cursor_expired" });
+}
+function aborted() {
+    return new DOMException("The operation was aborted", "AbortError");
+}

package/dist/src/runtime.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { BrokerClient, BrokerError } from "./client.js";
 import { StateStore } from "./store.js";
+import { RevisionPublisher } from "./revisions.js";
 export class BrokerRuntime {
     config;
     hooks;
@@ -10,6 +11,8 @@ export class BrokerRuntime {
     store;
     timer;
     delivering = false;
+    ready = false;
+    revisions = new RevisionPublisher();
     constructor(config, hooks) {
         this.config = config;
         this.hooks = hooks;
@@ -25,6 +28,8 @@ export class BrokerRuntime {
         this.store.retainSources([...this.sources.keys()]);
         this.store.pruneExpired();
         await Promise.all([...this.sources.values()].map((source) => this.startSource(source)));
+        this.ready = true;
+        this.publishSnapshot();
         this.timer = setInterval(() => {
             void this.reconcileAll();
             void this.deliverPending();
@@ -32,21 +37,32 @@ export class BrokerRuntime {
         this.timer.unref();
     }
     async stop() {
+        this.ready = false;
         if (this.timer)
             clearInterval(this.timer);
         for (const source of this.sources.values())
             source.abort?.abort();
+        this.revisions.close();
         this.store?.close();
         this.store = undefined;
     }
     snapshot() {
+        return this.revisions.snapshot();
+    }
+    waitForSnapshot(cursor, waitSeconds, signal) {
+        return this.revisions.wait(cursor, waitSeconds, signal);
+    }
+    snapshotMaterial() {
         return {
             sources: [...this.health.values()].sort((a, b) => a.id.localeCompare(b.id)),
-            requests: [...this.requests.values()].sort((a, b) => b.requested_at.localeCompare(a.requested_at)),
-            synchronizedAt: new Date().toISOString(),
-            deliveryFailures: this.store?.failedDeliveryCount() ?? 0,
+            requests: [...this.requests.values()].sort((a, b) => b.request.requested_at.localeCompare(a.request.requested_at)),
+            delivery_failures: this.store?.failedDeliveryCount() ?? 0,
         };
     }
+    publishSnapshot() {
+        if (this.ready)
+            this.revisions.publish(this.snapshotMaterial());
+    }
     async decide(handle, action, expectedRevision, actor, options = {}) {
         const resolved = this.requireStore().resolve(handle);
         if (!resolved)
@@ -67,14 +83,13 @@ export class BrokerRuntime {
                 (options.constraints.duration_seconds !== undefined &&
                     options.constraints.duration_seconds > bounds.max_duration_seconds) ||
                 (options.constraints.max_uses !== undefined &&
-                    options.constraints.max_uses > bounds.max_uses))
+                    !validUseConstraint(options.constraints.max_uses, bounds.max_uses)))
                 throw new Error("action_not_allowed");
         }
         const decision = {
             expected_revision: expectedRevision,
             idempotency_key: deterministicDecisionKey(resolved.sourceId, resolved.requestId, expectedRevision, action, actor),
             on_behalf_of: actor,
-            ...(options.reason ? { decision_reason: options.reason } : {}),
             ...(options.constraints ? { constraints: options.constraints } : {}),
         };
         const updated = await this.decideWithRecovery(source, resolved.requestId, action, decision);
@@ -149,15 +164,17 @@ export class BrokerRuntime {
             } while (cursor);
         }
         for (const request of [...this.requests.values()])
-            if (request.sourceId === source.config.id && !seen.has(request.id)) {
+            if (request.source_id === source.config.id &&
+                !seen.has(request.request.id)) {
                 this.requests.delete(request.handle);
-                this.requireStore().remove(source.config.id, request.id);
+                this.requireStore().remove(source.config.id, request.request.id);
             }
         this.requireStore().retainRequests(source.config.id, seen);
         this.requireStore().pruneExpired();
         if (eventCursor)
             this.requireStore().setCursor(source.config.id, eventCursor);
         this.markHealthy(source);
+        this.publishSnapshot();
     }
     watch(source) {
         source.abort?.abort();
@@ -206,19 +223,25 @@ export class BrokerRuntime {
         source.discovered = true;
     }
     markHealthy(source) {
+        const current = this.health.get(source.config.id);
+        if (current?.healthy)
+            return;
         this.health.set(source.config.id, {
             id: source.config.id,
             label: source.config.label,
             healthy: true,
-            lastSyncAt: new Date().toISOString(),
+            last_sync_at: new Date().toISOString(),
         });
+        this.publishSnapshot();
     }
     accept(source, request) {
         if (request.status !== "pending" && request.status !== "active") {
             this.requireStore().remove(source.config.id, request.id);
             for (const [handle, current] of this.requests)
-                if (current.sourceId === source.config.id && current.id === request.id)
+                if (current.source_id === source.config.id &&
+                    current.request.id === request.id)
                     this.requests.delete(handle);
+            this.publishSnapshot();
             return;
         }
         const expires = Date.parse(request.pending_expires_at ??
@@ -226,20 +249,21 @@ export class BrokerRuntime {
             new Date(Date.now() + 86_400_000).toISOString());
         const handle = this.requireStore().handle(source.config.id, request.id, request.revision, expires);
         for (const [old, current] of this.requests)
-            if (current.sourceId === source.config.id &&
-                current.id === request.id &&
+            if (current.source_id === source.config.id &&
+                current.request.id === request.id &&
                 old !== handle)
                 this.requests.delete(old);
         this.requests.set(handle, this.project(source, request, handle));
         this.requireStore().enqueue(handle);
+        this.publishSnapshot();
         void this.deliverPending();
     }
     project(source, request, handle) {
         return {
-            ...request,
-            sourceId: source.config.id,
-            sourceLabel: source.config.label,
+            source_id: source.config.id,
+            source_label: source.config.label,
             handle,
+            request,
         };
     }
     markUnhealthy(source, error) {
@@ -250,6 +274,7 @@ export class BrokerRuntime {
             healthy: false,
             error: safeError(message),
         });
+        this.publishSnapshot();
         this.hooks.log("warn", `BrokerKit source ${source.config.id} unavailable: ${safeError(message)}`);
     }
     requireStore() {
@@ -271,9 +296,11 @@ export class BrokerRuntime {
                 try {
                     await this.hooks.deliver(delivery, notificationText(request));
                     this.store?.markDelivered(delivery.id, delivery.handle);
+                    this.publishSnapshot();
                 }
                 catch {
                     this.store?.markDeliveryError(delivery.id, delivery.handle, delivery.attempts);
+                    this.publishSnapshot();
                 }
             }));
         }
@@ -282,6 +309,13 @@ export class BrokerRuntime {
         }
     }
 }
+function validUseConstraint(value, maximum) {
+    if (value === null)
+        return maximum === null;
+    return (Number.isSafeInteger(value) &&
+        value > 0 &&
+        (maximum === null || value <= maximum));
+}
 function deterministicDecisionKey(source, request, revision, action, actor) {
     return createHash("sha256")
         .update([
@@ -301,11 +335,12 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function notificationText(request) {
+    const value = request.request;
     return [
-        `${request.sourceLabel}: ${request.presentation.title}`,
-        request.presentation.summary ?? "",
+        `${request.source_label}: ${value.presentation.title}`,
+        value.presentation.summary ?? "",
         `Handle: ${request.handle}`,
-        ...request.allowed_actions.map((action) => `/brokerkit ${action} ${request.handle}`),
+        ...value.allowed_actions.map((action) => `/brokerkit ${action} ${request.handle}`),
     ]
         .filter(Boolean)
         .join("\n");