@byokit/openclaw 0.1.0

package/engine/package.json

@@ -0,0 +1 @@
+{"name":"byokit-openclaw-engine","version":"0.1.0","type":"module","private":true,"dependencies":{"openclaw":"2026.8.1"}}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@byokit/openclaw",
+  "version": "0.1.0",
+  "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/openclaw"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./device": {
+      "react-native": {
+        "types": "./dist/device.d.ts",
+        "default": "./dist/device.js"
+      },
+      "browser": {
+        "types": "./dist/device.d.ts",
+        "default": "./dist/device.js"
+      },
+      "types": "./dist/device.d.ts",
+      "default": "./dist/device.js"
+    },
+    "./link": {
+      "types": "./dist/link.d.ts",
+      "default": "./dist/link.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "engine",
+    "plugin",
+    "policy",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
+  },
+  "dependencies": {
+    "@byokit/link": "0.3.2",
+    "@byokit/relay": "0.2.1",
+    "@byokit/reach": "0.2.0",
+    "@byokit/seal": "0.1.0",
+    "@openclaw/gateway-client": "2026.8.1",
+    "@openclaw/gateway-protocol": "2026.8.1",
+    "ws": "8.21.3"
+  },
+  "devDependencies": {
+    "@byokit/ui-core": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/index.js

@@ -0,0 +1,183 @@
+// The BYOKit bridge plugin (docs/runtime-kits.md 5.9): tool calls gated by the fail-closed unix-socket bridge.
+// Runs in the gateway process. Reads its tool table from the sibling tools.json written by writePlugin, so
+// schemas and descriptions stay app data. No imports beyond node builtins: nothing here needs resolving in-gateway.
+import { connect } from 'node:net';
+import { readFileSync } from 'node:fs';
+
+/** TypeBox's Kind is a global symbol, so these schemas are valid TypeBox without importing typebox. */
+const Kind = Symbol.for('TypeBox.Kind');
+
+const table = JSON.parse(readFileSync(new URL('./tools.json', import.meta.url), 'utf8'));
+const RUN_PARAM = table.runParam;
+const PERMIT_PARAM = table.permitParam;
+const TOOLS = new Map(table.tools.map((t) => [t.name, t]));
+// Absent (a table from before the flag) reads as true: fail closed.
+const GATE_BUILTINS = table.gateBuiltins !== false;
+
+/** Minimal JSON Schema -> TypeBox-marked schema converter; output is both valid TypeBox and valid JSON Schema. */
+function toTypeBox(schema) {
+  if (schema === true) return { [Kind]: 'Any' };
+  if (typeof schema !== 'object' || schema === null || Array.isArray(schema)) return { [Kind]: 'Any' };
+  const out = { ...schema };
+  const kind =
+    schema.const !== undefined ? 'Literal'
+    : Array.isArray(schema.enum) ? 'Union'
+    : schema.anyOf !== undefined ? 'Union'
+    : schema.oneOf !== undefined ? 'Union'
+    : schema.allOf !== undefined ? 'Intersect'
+    : schema.type === 'object' || (schema.type === undefined && (schema.properties !== undefined || schema.required !== undefined)) ? 'Object'
+    : schema.type === 'array' ? 'Array'
+    : schema.type === 'string' ? 'String'
+    : schema.type === 'number' ? 'Number'
+    : schema.type === 'integer' ? 'Integer'
+    : schema.type === 'boolean' ? 'Boolean'
+    : schema.type === 'null' ? 'Null'
+    : 'Any';
+  out[Kind] = kind;
+  if (kind === 'Literal') out.const = schema.const;
+  if (Array.isArray(schema.enum)) out.anyOf = schema.enum.map((v) => ({ [Kind]: 'Literal', const: v }));
+  if (Array.isArray(schema.anyOf)) out.anyOf = schema.anyOf.map(toTypeBox);
+  if (Array.isArray(schema.oneOf)) out.oneOf = schema.oneOf.map(toTypeBox);
+  if (Array.isArray(schema.allOf)) out.allOf = schema.allOf.map(toTypeBox);
+  if (out.properties && typeof out.properties === 'object') {
+    out.properties = Object.fromEntries(Object.entries(out.properties).map(([k, v]) => [k, toTypeBox(v)]));
+  }
+  if (out.items !== undefined) {
+    out.items = Array.isArray(out.items) ? out.items.map(toTypeBox) : toTypeBox(out.items);
+  }
+  if (out.additionalProperties !== undefined && typeof out.additionalProperties === 'object') {
+    out.additionalProperties = toTypeBox(out.additionalProperties);
+  }
+  return out;
+}
+
+/** One newline-framed request over the bridge socket: one connection, one request, then close. */
+function bridgeRequest(message, { timeoutMs, signal } = {}) {
+  const path = process.env.BYOKIT_BRIDGE_SOCK;
+  if (!path) return Promise.reject(new Error("can't check this action right now"));
+  return new Promise((resolve, reject) => {
+    const socket = connect(path);
+    let buffer = '';
+    let done = false;
+    let timer;
+    const fail = (error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      socket.destroy();
+      reject(error);
+    };
+    const abort = () => fail(new Error('the call was cancelled'));
+    if (signal) {
+      if (signal.aborted) return abort();
+      signal.addEventListener('abort', abort, { once: true });
+    }
+    socket.once('error', () => fail(new Error("can't check this action right now")));
+    socket.on('data', (chunk) => {
+      buffer += String(chunk);
+      if (buffer.length > 1_000_000) return fail(new Error("can't check this action right now"));
+      const end = buffer.indexOf('\n');
+      if (end < 0) return;
+      done = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      socket.end();
+      try {
+        resolve(JSON.parse(buffer.slice(0, end)));
+      } catch {
+        fail(new Error("can't check this action right now"));
+      }
+    });
+    socket.once('connect', () => {
+      timer = setTimeout(() => fail(new Error("can't check this action right now")), timeoutMs ?? 195_000);
+      socket.write(JSON.stringify(message) + '\n');
+    });
+  });
+}
+
+async function gate(key, tool, input, signal) {
+  const reply = await bridgeRequest({ kind: 'gate', key, tool, input }, { timeoutMs: 195_000, signal });
+  return reply && typeof reply === 'object' ? reply : { allow: false, reason: "can't check this action right now" };
+}
+
+export default {
+  id: table.id,
+  name: 'BYOKit bridge',
+  description: 'Gates tool calls through the host app before they run.',
+  configSchema: {
+    safeParse(value) {
+      if (value === undefined) return { success: true, data: undefined };
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return { success: false, error: 'expected config object' };
+      if (Object.keys(value).length > 0) return { success: false, error: 'config must be empty' };
+      return { success: true, data: value };
+    },
+    jsonSchema: { type: 'object', additionalProperties: false, properties: {} },
+  },
+  register(api) {
+    for (const spec of table.tools) {
+      api.registerTool({
+        name: spec.name,
+        label: spec.name,
+        description: spec.description,
+        parameters: toTypeBox(spec.parameters),
+        async execute(_toolCallId, params, signal) {
+          const input = { ...(params ?? {}) };
+          const run = input[RUN_PARAM];
+          const permit = input[PERMIT_PARAM];
+          delete input[RUN_PARAM];
+          delete input[PERMIT_PARAM];
+          // The run key is always required; the permit only rides along when the gate minted one (N1).
+          if (typeof run !== 'string') {
+            throw new Error('this tool needs approval before it runs');
+          }
+          const call = { kind: 'call', key: run, tool: spec.name, input };
+          if (typeof permit === 'string') call.permit = permit;
+          let reply;
+          try {
+            reply = await bridgeRequest(call, { timeoutMs: 195_000, signal });
+          } catch (error) {
+            throw new Error(error instanceof Error ? error.message : "can't check this action right now");
+          }
+          if (reply && typeof reply === 'object' && reply.ok === true && typeof reply.text === 'string') {
+            return { content: [{ type: 'text', text: reply.text }], details: {} };
+          }
+          const reason =
+            reply && typeof reply === 'object' && typeof reply.reason === 'string'
+              ? reply.reason
+              : "can't check this action right now";
+          throw new Error(reason);
+        },
+      });
+    }
+    api.on('before_tool_call', async (event, ctx) => {
+      // Engine builtins (web_fetch, memory, ...) are gated too unless the app opted out; they run in-engine and
+      // never call back, so an allow passes them through unchanged.
+      const builtin = !TOOLS.has(event.toolName);
+      if (builtin && !GATE_BUILTINS) return undefined;
+      const key = ctx?.sessionKey;
+      if (typeof key !== 'string' || !key) return { block: true, blockReason: "can't check this action right now" };
+      let decision;
+      try {
+        decision = await gate(key, event.toolName, event.params ?? {}, ctx?.abortSignal);
+      } catch (error) {
+        return { block: true, blockReason: error instanceof Error ? error.message : "can't check this action right now" };
+      }
+      if (!decision.allow) {
+        return {
+          block: true,
+          blockReason: typeof decision.reason === 'string' ? decision.reason : "can't check this action right now",
+        };
+      }
+      if (builtin) return undefined;
+      // The bridge mints a permit for permitted tools and admits the rest ticket-side; either way the run key
+      // rides along and execute sends back only what the gate gave it (N1).
+      return {
+        params: {
+          ...(event.params ?? {}),
+          [RUN_PARAM]: key,
+          ...(typeof decision.permit === 'string' ? { [PERMIT_PARAM]: decision.permit } : {}),
+        },
+      };
+    });
+  },
+};

package/plugin/package.json

@@ -0,0 +1 @@
+{"name":"byokit-openclaw-bridge","version":"0.1.0","type":"module","openclaw":{"extensions":["./index.js"]}}

package/policy/policy.mjs

@@ -0,0 +1,197 @@
+// The operator install policy (docs/runtime-kits.md 5.9): run as a command by OpenClaw's security.installPolicy,
+// not imported. Reads one protocol-1 request on stdin, prints one protocol-1 envelope on stdout. Fail closed:
+// anything unverifiable is a block.
+//
+// Inputs from the environment (set by the kit's installPolicy config):
+//   BYOKIT_TRUSTED_SKILLS  path to the trusted-skills JSON file (Crewhouse's trusted-skills.json shape):
+//                          either a list [{ id|name, version, sha256|hash }] or a map { "<id>": { version, sha256 } }.
+//   BYOKIT_OWN_ROOTS        JSON array of own content roots; skills sourced under them are the app's own.
+// Rules: any request kind containing 'depend' is blocked everywhere (own roots included);
+// dependency installers (a skill installSpec carrying bins/formula/package/module/url/archive) are blocked;
+// skill installs are allowed only from own roots or with an exact id + version + SKILL.md sha256 trusted match
+// (the version is request.origin.version when present, else the SKILL.md frontmatter version);
+// plugin installs are allowed only in the @openclaw/ scope.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
+const allow = (findings) => ({ protocolVersion: 1, decision: 'allow', ...(findings ? { findings } : {}) });
+const block = (reason, findings) => ({
+  protocolVersion: 1,
+  decision: 'block',
+  reason,
+  ...(findings && findings.length > 0 ? { findings } : {}),
+});
+
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** The trusted-skills file, tolerated in list or map shape with several key spellings. */
+function loadTrusted() {
+  const path = process.env.BYOKIT_TRUSTED_SKILLS;
+  if (!path || !existsSync(path)) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return [];
+  }
+  const entries = [];
+  const push = (id, entry) => {
+    if (typeof id !== 'string' || !id) return;
+    const version =
+      isRecord(entry) && (typeof entry.version === 'string' ? entry.version : undefined);
+    const sha =
+      (isRecord(entry) && typeof entry.sha256 === 'string' && entry.sha256) ||
+      (isRecord(entry) && typeof entry.hash === 'string' && entry.hash) ||
+      (typeof entry === 'string' && entry) ||
+      undefined;
+    entries.push({ id, version, sha });
+  };
+  if (Array.isArray(parsed)) {
+    for (const entry of parsed) {
+      if (typeof entry === 'string') push(entry, undefined);
+      else if (isRecord(entry)) push(entry.id ?? entry.name, entry);
+    }
+  } else if (isRecord(parsed)) {
+    for (const [id, entry] of Object.entries(parsed)) push(id, entry);
+  }
+  return entries;
+}
+
+function ownRoots() {
+  try {
+    const roots = JSON.parse(process.env.BYOKIT_OWN_ROOTS ?? '[]');
+    return Array.isArray(roots) ? roots.filter((r) => typeof r === 'string').map((r) => resolve(r)) : [];
+  } catch {
+    return [];
+  }
+}
+
+const inside = (root, p) => {
+  const rel = relative(root, resolve(p));
+  return rel !== '' && !rel.startsWith('..');
+};
+
+/** First `name:`/`version:` scalars of the SKILL.md frontmatter, plus the sha256 of the file bytes. */
+function skillIdentity(sourcePath) {
+  let bytes;
+  try {
+    const file = resolve(sourcePath, 'SKILL.md');
+    if (!statSync(file).isFile()) return undefined;
+    bytes = readFileSync(file);
+  } catch {
+    return undefined;
+  }
+  const text = bytes.toString('utf8');
+  let name;
+  let version;
+  if (text.startsWith('---')) {
+    const end = text.indexOf('\n---', 3);
+    const front = text.slice(3, end < 0 ? 0 : end);
+    for (const line of front.split('\n')) {
+      const m = /^\s*(name|version)\s*:\s*(.+?)\s*$/.exec(line);
+      if (m) {
+        const value = m[2].replace(/^['"]|['"]$/g, '');
+        if (m[1] === 'name') name = value;
+        else version = value;
+      }
+    }
+  }
+  return { name, version, sha256: createHash('sha256').update(bytes).digest('hex') };
+}
+
+const INSTALLER_FIELDS = ['bins', 'formula', 'package', 'module', 'url', 'archive'];
+
+function decideSkill(request, trusted, roots) {
+  const kind =
+    isRecord(request.request) && typeof request.request.kind === 'string' ? request.request.kind : undefined;
+  if (kind !== undefined && /depend/i.test(kind)) {
+    return block(`dependency installs are not allowed: ${kind}`, [
+      { ruleId: 'dependency-installer', severity: 'critical', message: `request kind ${kind} fetches dependencies` },
+    ]);
+  }
+  const spec = isRecord(request.skill) && isRecord(request.skill.installSpec) ? request.skill.installSpec : {};
+  for (const field of INSTALLER_FIELDS) {
+    if (spec[field] !== undefined) {
+      return block(`skill installs that fetch ${field} are not allowed`, [
+        { ruleId: 'dependency-installer', severity: 'critical', message: `installSpec carries ${field}` },
+      ]);
+    }
+  }
+  const sourcePath = typeof request.sourcePath === 'string' ? request.sourcePath : undefined;
+  if (!sourcePath) return block('skill source is not verifiable');
+  if (roots.some((root) => inside(root, sourcePath) || resolve(sourcePath) === root)) return allow();
+  const identity = skillIdentity(sourcePath);
+  if (!identity) return block('skill SKILL.md is not verifiable');
+  // Bundled skills carry no frontmatter version; the reviewed version travels on request.origin.version.
+  const originVersion =
+    isRecord(request.origin) && typeof request.origin.version === 'string' ? request.origin.version : undefined;
+  const candidateVersion = originVersion ?? identity.version;
+  const ids = [spec.id, request.targetName, identity.name].filter((v) => typeof v === 'string');
+  const hit = trusted.find(
+    (entry) =>
+      ids.includes(entry.id) &&
+      (entry.version === undefined && candidateVersion === undefined || entry.version === candidateVersion) &&
+      entry.sha !== undefined &&
+      entry.sha.toLowerCase() === identity.sha256.toLowerCase(),
+  );
+  if (!hit) return block(`skill ${ids[0] ?? request.targetName} is not a trusted skill`);
+  return allow();
+}
+
+function decidePlugin(request) {
+  const plugin = isRecord(request.plugin) ? request.plugin : {};
+  const scope = [plugin.packageName, plugin.pluginId, request.targetName].find((v) => typeof v === 'string');
+  if (!scope || !scope.startsWith('@openclaw/')) {
+    return block(`only the @openclaw/ plugin scope is allowed, not ${scope ?? request.targetName}`);
+  }
+  // N4: the scope name above is self-declared (the candidate manifest's own
+  // `name`). Allow only with engine proof of registry origin on the pinned
+  // engine: source.kind 'npm' (engine-derived from the install request kind;
+  // npm installs always carry authority 'third-party') plus the
+  // operator-requested specifier in the @openclaw/ scope. Anything else is a
+  // local/archive/git/file candidate spoofing the name. Fail closed.
+  const source = isRecord(request.source) ? request.source : undefined;
+  const specifier =
+    isRecord(request.request) && typeof request.request.requestedSpecifier === 'string'
+      ? request.request.requestedSpecifier
+      : undefined;
+  if (source?.kind === 'npm' && specifier !== undefined && specifier.startsWith('@openclaw/')) return allow();
+  return block(`@openclaw/ plugin install is not from the npm registry: ${specifier ?? request.targetName}`, [
+    { ruleId: 'plugin-source', severity: 'critical', message: 'self-declared @openclaw/ name without registry source proof' },
+  ]);
+}
+
+function decide(request) {
+  if (!isRecord(request) || request.protocolVersion !== 1) return block('unknown policy protocol');
+  if (request.targetType === 'plugin') return decidePlugin(request);
+  if (request.targetType === 'skill') return decideSkill(request, loadTrusted(), ownRoots());
+  return block(`unknown install target ${String(request.targetType)}`);
+}
+
+function main() {
+  let input = '';
+  const fail = (reason) => {
+    process.stdout.write(JSON.stringify(block(reason)) + '\n');
+  };
+  try {
+    input = readFileSync(0, 'utf8');
+  } catch {
+    fail('policy could not read its request');
+    return;
+  }
+  if (Buffer.byteLength(input, 'utf8') > 1024 * 1024) {
+    fail('policy request too large');
+    return;
+  }
+  let request;
+  try {
+    request = JSON.parse(input);
+  } catch {
+    fail('policy request is not JSON');
+    return;
+  }
+  process.stdout.write(JSON.stringify(decide(request)) + '\n');
+}
+
+main();