browsermesh-kernel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clawser Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# browsermesh-kernel
+
+Capability-secure browser microkernel: resource handles, ByteStreams, IPC,
+service mesh, structured tracing, chaos engineering, and tenant isolation —
+zero npm dependencies, pure ES modules.
+
+## Modules
+
+| Module | Key Exports |
+|--------|-------------|
+| constants / errors | `KERNEL_DEFAULTS`, `KERNEL_CAP`, `KERNEL_ERROR`, `KernelError` + 7 subclasses |
+| resource-table | `ResourceTable` — handle-based `res_N` resource allocation |
+| byte-stream | `BYTE_STREAM`, `isByteStream`, `asByteStream`, `createPipe`, `pipe`, `devNull`, `compose` |
+| clock / rng | `Clock` (fixed for testing), `RNG` (seeded xorshift128+) |
+| caps | `buildCaps`, `requireCap`, `CapsBuilder` — capability enforcement |
+| message-port | `KernelMessagePort`, `createChannel` — IPC |
+| service-registry | `ServiceRegistry` — `svc://` service lookup with `onLookupMiss` |
+| tracer | `Tracer` — ring-buffer, `AsyncIterable` trace event stream |
+| logger | `Logger`, `LOG_LEVEL` |
+| chaos | `ChaosEngine` — fault injection |
+| env | `Environment` — immutable env vars |
+| signal / stdio | `SIGNAL`, `SignalController` (TERM/INT/HUP + `AbortSignal`), `Stdio` |
+| kernel | `Kernel` — the facade tying every subsystem together |
+
+## Install
+
+```bash
+npm install browsermesh-kernel
+```
+
+## Usage
+
+```js
+import { Kernel, KERNEL_CAP } from 'browsermesh-kernel'
+
+const kernel = new Kernel()
+
+// Create a tenant with scoped capabilities
+const tenant = kernel.createTenant({
+  capabilities: [KERNEL_CAP.CLOCK, KERNEL_CAP.IPC, KERNEL_CAP.STDIO],
+  env: { MODE: 'sandbox' },
+})
+
+// Use kernel subsystems
+const handle = kernel.resources.allocate('stream', myStream, tenant.id)
+kernel.tracer.emit({ type: 'custom', tenant: tenant.id })
+
+// Clean up
+kernel.destroyTenant(tenant.id)
+kernel.close()
+```
+
+## Origin
+
+Extracted from the [clawser](https://github.com/johnhenry/clawser) browser
+agent workspace, where it underpins workspace tenants, shell pipes, MCP
+service registration, provider cost tracing, sandboxed code execution, and
+daemon IPC — all as opt-in hooks (`clawser-kernel-integration.js`) that are
+no-ops when the kernel isn't active.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "browsermesh-kernel",
+  "version": "0.1.0",
+  "description": "Capability-secure browser microkernel with resource handles, IPC, tracing, and chaos engineering",
+  "type": "module",
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "microkernel",
+    "capabilities",
+    "ipc",
+    "tracing",
+    "chaos",
+    "browser"
+  ],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/johnhenry/clawser" }
+}

package/src/byte-stream.mjs

@@ -0,0 +1,258 @@
+/**
+ * ByteStream — duck-typed stream protocol with utilities.
+ *
+ * Provides a protocol symbol, type checking, pipe utilities, and an in-memory
+ * pipe factory built on an internal AsyncBuffer (matching netway's pattern).
+ * EOF propagation on error ensures paired endpoints close cleanly.
+ *
+ * @module byte-stream
+ */
+
+import { StreamClosedError } from './errors.mjs';
+import { KERNEL_DEFAULTS } from './constants.mjs';
+
+/**
+ * Symbol used to tag objects as ByteStream-compliant.
+ */
+export const BYTE_STREAM = Symbol.for('kernel.ByteStream');
+
+/**
+ * Check whether an object conforms to the ByteStream protocol.
+ * A ByteStream must have `read`, `write`, and `close` methods.
+ *
+ * @param {*} obj - The object to check.
+ * @returns {boolean}
+ */
+export function isByteStream(obj) {
+  return obj != null &&
+    typeof obj.read === 'function' &&
+    typeof obj.write === 'function' &&
+    typeof obj.close === 'function';
+}
+
+/**
+ * Tag an object with the ByteStream symbol. Idempotent — already tagged
+ * objects are returned as-is.
+ *
+ * @param {Object} obj - The object to tag (must have read/write/close).
+ * @returns {Object} The tagged object.
+ */
+export function asByteStream(obj) {
+  if (obj[BYTE_STREAM]) return obj;
+  obj[BYTE_STREAM] = true;
+  return obj;
+}
+
+/**
+ * Simple asynchronous FIFO buffer with blocking pull semantics.
+ * Matches netway's AsyncBuffer pattern. EOF propagation on error.
+ *
+ * @private
+ */
+class AsyncBuffer {
+  #queue = [];
+  #waiters = [];
+  #writeClosed = false;
+  #readClosed = false;
+  #paused = false;
+  #highWaterMark;
+
+  constructor({ highWaterMark = 0 } = {}) {
+    this.#highWaterMark = highWaterMark;
+  }
+
+  push(data) {
+    if (this.#writeClosed || this.#readClosed) return false;
+    if (this.#waiters.length > 0) {
+      this.#waiters.shift()(data);
+      return true;
+    }
+    this.#queue.push(data);
+    if (this.#highWaterMark > 0 && this.#queue.length >= this.#highWaterMark) {
+      this.#paused = true;
+      return false;
+    }
+    return true;
+  }
+
+  pull() {
+    if (this.#queue.length > 0) {
+      const item = this.#queue.shift();
+      // Resume writes when queue drains below high-water mark
+      if (this.#paused && this.#queue.length < this.#highWaterMark) {
+        this.#paused = false;
+      }
+      return Promise.resolve(item);
+    }
+    if (this.#writeClosed || this.#readClosed) return Promise.resolve(null);
+    return new Promise(resolve => this.#waiters.push(resolve));
+  }
+
+  /** @returns {boolean} Whether the buffer is accepting writes */
+  get writable() { return !this.#writeClosed && !this.#readClosed && !this.#paused; }
+
+  /** Signal no more writes — existing buffered data can still be drained. */
+  closeWrite() {
+    this.#writeClosed = true;
+    this.#paused = false;
+    // Resolve waiters so blocked reads get null after queue is drained
+    for (const w of this.#waiters) w(null);
+    this.#waiters.length = 0;
+  }
+
+  /** Hard close — discard everything. */
+  closeRead() {
+    this.#readClosed = true;
+    this.#writeClosed = true;
+    this.#paused = false;
+    for (const w of this.#waiters) w(null);
+    this.#waiters.length = 0;
+    this.#queue.length = 0;
+  }
+
+  get isClosed() { return this.#writeClosed && this.#readClosed; }
+}
+
+/**
+ * Create an in-memory pipe returning `[reader, writer]` ByteStreams.
+ * Data written to `writer` can be read from `reader`. Closing either
+ * endpoint propagates EOF to the other.
+ *
+ * @param {Object} [opts={}]
+ * @param {number} [opts.highWaterMark=1024] - Maximum queue depth.
+ * @returns {[Object, Object]} `[reader, writer]` ByteStream pair.
+ */
+export function createPipe({ highWaterMark = KERNEL_DEFAULTS.DEFAULT_STREAM_BUFFER_SIZE } = {}) {
+  const buffer = new AsyncBuffer({ highWaterMark });
+  let readerClosed = false;
+  let writerClosed = false;
+
+  const reader = {
+    [BYTE_STREAM]: true,
+    async read() {
+      if (readerClosed) return null;
+      return buffer.pull();
+    },
+    async write() {
+      throw new StreamClosedError();
+    },
+    async close() {
+      if (readerClosed) return;
+      readerClosed = true;
+      buffer.closeRead();
+    },
+    get closed() { return readerClosed; },
+  };
+
+  const writer = {
+    [BYTE_STREAM]: true,
+    async read() {
+      throw new StreamClosedError();
+    },
+    async write(data) {
+      if (writerClosed) throw new StreamClosedError();
+      if (!buffer.push(data)) {
+        writerClosed = true;
+        throw new StreamClosedError();
+      }
+    },
+    async close() {
+      if (writerClosed) return;
+      writerClosed = true;
+      // Signal EOF — existing data can still be drained by reader
+      buffer.closeWrite();
+    },
+    get closed() { return writerClosed; },
+  };
+
+  return [reader, writer];
+}
+
+/**
+ * Pipe all data from a source ByteStream to a destination ByteStream.
+ * Reads from src until null (EOF), writes each chunk to dst.
+ * On transport error, closes both endpoints for clean EOF propagation.
+ *
+ * @param {Object} src - Source ByteStream.
+ * @param {Object} dst - Destination ByteStream.
+ * @returns {Promise<void>}
+ */
+export async function pipe(src, dst) {
+  try {
+    let chunk;
+    while ((chunk = await src.read()) !== null) {
+      await dst.write(chunk);
+    }
+  } catch (err) {
+    // EOF propagation on error — close both endpoints
+    await src.close().catch(() => {});
+    await dst.close().catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Create a sink ByteStream that discards all writes and returns null on read.
+ *
+ * @returns {Object} A ByteStream that acts as `/dev/null`.
+ */
+export function devNull() {
+  return {
+    [BYTE_STREAM]: true,
+    async read() { return null; },
+    async write() {},
+    async close() {},
+    get closed() { return false; },
+  };
+}
+
+/**
+ * Transform protocol. A transform has a single method:
+ *   `transform(chunk: Uint8Array) → Uint8Array | Promise<Uint8Array>`
+ *
+ * Transforms can be composed onto any ByteStream to create processing
+ * pipelines (compression, encryption, tracing, rate-limiting, etc.).
+ */
+
+/**
+ * Compose one or more transforms onto a ByteStream, returning a new
+ * ByteStream that applies the transforms in order on read and in
+ * reverse order on write.
+ *
+ * @param {Object} stream - The underlying ByteStream.
+ * @param {...{ transform: function(Uint8Array): Uint8Array|Promise<Uint8Array> }} transforms - Transform objects.
+ * @returns {Object} A new ByteStream with transforms applied.
+ */
+export function compose(stream, ...transforms) {
+  if (transforms.length === 0) return stream;
+
+  return {
+    [BYTE_STREAM]: true,
+
+    async read() {
+      const chunk = await stream.read();
+      if (chunk === null) return null;
+      let result = chunk;
+      for (const t of transforms) {
+        result = await t.transform(result);
+      }
+      return result;
+    },
+
+    async write(data) {
+      let result = data;
+      // Apply inverse transforms in reverse for writes (fall back to transform if no untransform)
+      for (let i = transforms.length - 1; i >= 0; i--) {
+        const t = transforms[i];
+        result = await (t.untransform ? t.untransform(result) : t.transform(result));
+      }
+      await stream.write(result);
+    },
+
+    async close() {
+      await stream.close();
+    },
+
+    get closed() { return stream.closed; },
+  };
+}

package/src/caps.mjs

@@ -0,0 +1,102 @@
+/**
+ * Caps — capability builder and enforcement.
+ *
+ * Builds a frozen capabilities object from a kernel instance and a set
+ * of granted capability tags. The `requireCap` function enforces access
+ * control by throwing CapabilityDeniedError for missing capabilities.
+ *
+ * @module caps
+ */
+
+import { KERNEL_CAP } from './constants.mjs';
+import { CapabilityDeniedError } from './errors.mjs';
+
+/**
+ * Build a frozen capabilities object from granted capability tags.
+ * Each granted tag maps to the corresponding kernel subsystem reference.
+ *
+ * @param {Object} kernel - Kernel instance with subsystem accessors.
+ * @param {string[]} grantedCaps - Array of KERNEL_CAP tags to grant.
+ * @returns {Readonly<Object>} Frozen capabilities object.
+ */
+export function buildCaps(kernel, grantedCaps) {
+  const caps = {};
+  const granted = new Set(grantedCaps);
+  const hasAll = granted.has(KERNEL_CAP.ALL);
+
+  if (hasAll || granted.has(KERNEL_CAP.CLOCK)) {
+    caps.clock = kernel.clock;
+  }
+  if (hasAll || granted.has(KERNEL_CAP.RNG)) {
+    caps.rng = kernel.rng;
+  }
+  if (hasAll || granted.has(KERNEL_CAP.NET)) {
+    caps.net = true; // Network access marker — actual net object provided by netway
+  }
+  if (hasAll || granted.has(KERNEL_CAP.FS)) {
+    caps.fs = true; // FS access marker
+  }
+  if (hasAll || granted.has(KERNEL_CAP.IPC)) {
+    caps.ipc = kernel.services;
+  }
+  if (hasAll || granted.has(KERNEL_CAP.STDIO)) {
+    caps.stdio = true; // Stdio access marker — actual stdio is per-tenant
+  }
+  if (hasAll || granted.has(KERNEL_CAP.TRACE)) {
+    caps.trace = kernel.tracer;
+  }
+  if (hasAll || granted.has(KERNEL_CAP.CHAOS)) {
+    caps.chaos = kernel.chaos;
+  }
+  if (hasAll || granted.has(KERNEL_CAP.ENV)) {
+    caps.env = true; // Env access marker — actual env is per-tenant
+  }
+  if (hasAll || granted.has(KERNEL_CAP.SIGNAL)) {
+    caps.signal = true; // Signal access marker
+  }
+  if (hasAll || granted.has(KERNEL_CAP.MESH)) {
+    caps.mesh = true; // Mesh networking access marker
+  }
+  if (hasAll || granted.has(KERNEL_CAP.PAYMENT)) {
+    caps.payment = true; // Payment channel access marker
+  }
+  if (hasAll || granted.has(KERNEL_CAP.CONSENSUS)) {
+    caps.consensus = true; // Consensus protocol access marker
+  }
+
+  // Store the granted set for requireCap checks
+  caps._granted = Object.freeze([...granted]);
+
+  return Object.freeze(caps);
+}
+
+/**
+ * Require that a capability tag is present in a caps object.
+ *
+ * @param {Object} caps - Capabilities object from buildCaps.
+ * @param {string} capTag - The required KERNEL_CAP tag.
+ * @throws {CapabilityDeniedError} If the capability is not granted.
+ */
+export function requireCap(caps, capTag) {
+  if (!caps || !caps._granted) throw new CapabilityDeniedError(capTag);
+  const granted = new Set(caps._granted);
+  if (granted.has(KERNEL_CAP.ALL)) return;
+  if (granted.has(capTag)) return;
+  throw new CapabilityDeniedError(capTag);
+}
+
+/**
+ * Builder class for constructing capabilities (alternative to buildCaps).
+ */
+export class CapsBuilder {
+  /**
+   * Build capabilities from kernel and granted tags.
+   *
+   * @param {Object} kernel - Kernel instance.
+   * @param {string[]} grantedCaps - Granted capability tags.
+   * @returns {Readonly<Object>} Frozen capabilities object.
+   */
+  build(kernel, grantedCaps) {
+    return buildCaps(kernel, grantedCaps);
+  }
+}

package/src/chaos.mjs

@@ -0,0 +1,151 @@
+/**
+ * ChaosEngine — fault injection for testing and chaos engineering.
+ *
+ * Injects configurable latency, packet drops, disconnects, and network
+ * partitions. Supports global defaults and per-scope overrides. Uses RNG
+ * for deterministic fault patterns in replay mode.
+ *
+ * @module chaos
+ */
+
+/**
+ * Fault injection engine with global and per-scope configuration.
+ */
+export class ChaosEngine {
+  #enabled = false;
+  #globalConfig = { latencyMs: 0, dropRate: 0, disconnectRate: 0, partitionTargets: [] };
+  #scopeConfigs = new Map();
+  #rng;
+  #clock;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {Object} [opts.rng] - RNG instance for deterministic fault patterns.
+   * @param {Object} [opts.clock] - Clock instance for delay implementation.
+   */
+  constructor({ rng, clock } = {}) {
+    this.#rng = rng || null;
+    this.#clock = clock || null;
+  }
+
+  /**
+   * Enable the chaos engine. When disabled, all injection points are no-ops.
+   */
+  enable() {
+    this.#enabled = true;
+  }
+
+  /**
+   * Disable the chaos engine.
+   */
+  disable() {
+    this.#enabled = false;
+  }
+
+  /** Whether the engine is enabled. */
+  get enabled() { return this.#enabled; }
+
+  /**
+   * Configure global fault injection defaults.
+   *
+   * @param {Object} config
+   * @param {number} [config.latencyMs=0] - Added latency in ms.
+   * @param {number} [config.dropRate=0] - Drop probability (0-1).
+   * @param {number} [config.disconnectRate=0] - Disconnect probability (0-1).
+   * @param {string[]} [config.partitionTargets=[]] - Addresses to partition.
+   */
+  configure(config) {
+    this.#globalConfig = { ...this.#globalConfig, ...config };
+  }
+
+  /**
+   * Configure fault injection for a specific scope (overrides global).
+   *
+   * @param {string} scopeId - Scope identifier.
+   * @param {Object} config - Scope-specific configuration.
+   */
+  configureScope(scopeId, config) {
+    this.#scopeConfigs.set(scopeId, { ...config });
+  }
+
+  /**
+   * Remove scope-specific configuration, falling back to global defaults.
+   *
+   * @param {string} scopeId - Scope identifier.
+   */
+  removeScopeConfig(scopeId) {
+    this.#scopeConfigs.delete(scopeId);
+  }
+
+  /**
+   * Maybe inject latency delay.
+   *
+   * @param {string} [scopeId] - Optional scope for override lookup.
+   * @returns {Promise<void>}
+   */
+  async maybeDelay(scopeId) {
+    if (!this.#enabled) return;
+    const config = this.#getConfig(scopeId);
+    if (config.latencyMs <= 0) return;
+    if (this.#clock) {
+      await this.#clock.sleep(config.latencyMs);
+    } else {
+      await new Promise(resolve => setTimeout(resolve, config.latencyMs));
+    }
+  }
+
+  /**
+   * Check whether a packet/message should be dropped.
+   *
+   * @param {string} [scopeId] - Optional scope for override lookup.
+   * @returns {boolean}
+   */
+  shouldDrop(scopeId) {
+    if (!this.#enabled) return false;
+    const config = this.#getConfig(scopeId);
+    if (config.dropRate <= 0) return false;
+    return this.#random() < config.dropRate;
+  }
+
+  /**
+   * Check whether a connection should be forcibly disconnected.
+   *
+   * @param {string} [scopeId] - Optional scope for override lookup.
+   * @returns {boolean}
+   */
+  shouldDisconnect(scopeId) {
+    if (!this.#enabled) return false;
+    const config = this.#getConfig(scopeId);
+    if (config.disconnectRate <= 0) return false;
+    return this.#random() < config.disconnectRate;
+  }
+
+  /**
+   * Check whether an address is partitioned (unreachable).
+   *
+   * @param {string} addr - Target address.
+   * @param {string} [scopeId] - Optional scope for override lookup.
+   * @returns {boolean}
+   */
+  isPartitioned(addr, scopeId) {
+    if (!this.#enabled) return false;
+    const config = this.#getConfig(scopeId);
+    return (config.partitionTargets || []).includes(addr);
+  }
+
+  #getConfig(scopeId) {
+    if (scopeId && this.#scopeConfigs.has(scopeId)) {
+      return this.#scopeConfigs.get(scopeId);
+    }
+    return this.#globalConfig;
+  }
+
+  #random() {
+    if (this.#rng) {
+      const bytes = this.#rng.get(4);
+      const val = (bytes[0] | (bytes[1] << 8) | (bytes[2] << 16) | (bytes[3] << 24)) >>> 0;
+      return val / 0x100000000;
+    }
+    return Math.random();
+  }
+}

package/src/clock.mjs

@@ -0,0 +1,80 @@
+/**
+ * Clock — monotonic and wall-clock time abstraction.
+ *
+ * Provides both real and deterministic (fixed) clocks. The fixed clock
+ * is useful for testing — scheduled job logic becomes unit-testable
+ * without real timers.
+ *
+ * @module clock
+ */
+
+/**
+ * Clock providing monotonic and wall-clock time plus async sleep.
+ */
+export class Clock {
+  #monoFn;
+  #wallFn;
+  #sleepFn;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {function(): number} [opts.monoFn] - Monotonic time source (ms).
+   * @param {function(): number} [opts.wallFn] - Wall-clock time source (ms since epoch).
+   * @param {function(number): Promise<void>} [opts.sleepFn] - Async sleep implementation.
+   */
+  constructor({ monoFn, wallFn, sleepFn } = {}) {
+    this.#monoFn = monoFn || (() => performance.now());
+    this.#wallFn = wallFn || (() => Date.now());
+    this.#sleepFn = sleepFn || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  }
+
+  /**
+   * Get the current monotonic time in milliseconds.
+   * Monotonic time only moves forward and is not affected by clock adjustments.
+   *
+   * @returns {number} Monotonic timestamp in milliseconds.
+   */
+  nowMonotonic() {
+    return this.#monoFn();
+  }
+
+  /**
+   * Get the current wall-clock time in milliseconds since the Unix epoch.
+   *
+   * @returns {number} Wall-clock timestamp (ms since epoch).
+   */
+  nowWall() {
+    return this.#wallFn();
+  }
+
+  /**
+   * Sleep for the given number of milliseconds.
+   *
+   * @param {number} ms - Duration to sleep.
+   * @returns {Promise<void>}
+   */
+  async sleep(ms) {
+    return this.#sleepFn(ms);
+  }
+
+  /**
+   * Create a fixed (deterministic) clock for testing.
+   * The clock always returns the same values unless manually advanced.
+   *
+   * @param {number} mono - Fixed monotonic time value.
+   * @param {number} wall - Fixed wall-clock time value.
+   * @returns {Clock}
+   */
+  static fixed(mono, wall) {
+    let currentMono = mono;
+    let currentWall = wall;
+    return new Clock({
+      monoFn: () => currentMono,
+      wallFn: () => currentWall,
+      sleepFn: async (ms) => {
+        currentMono += ms;
+        currentWall += ms;
+      },
+    });
+  }
+}