@amaster.ai/employee-runtime-connector 0.1.5 → 0.1.7

package/dist/amaster-runtime.mjs

@@ -7,7 +7,7 @@ import { homedir, hostname } from "node:os";
 import { fileURLToPath } from "node:url";
 import { BUILD_SUPPORTED_CAPABILITIES } from "./amaster-runtime-daemon/capability-registry.mjs";
 
-const CONNECTOR_VERSION = "0.1.5";
+const CONNECTOR_VERSION = "0.1.7";
 
 const CONFIG_KEY_MAP = new Map([
   ["server_url", "AMASTER_EMPLOYEE_SERVER_URL"],

package/dist/pi-exact-source-read.mjs

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { isIP } from "node:net";
+import { dirname, join } from "node:path";
+import { createPublicNetworkScope } from "./public-network-scope.mjs";
+
+export const EXACT_SOURCE_READ_TOOL_NAME = "amaster_exact_source_read";
+const MAX_REDIRECTS = 5;
+const MAX_BYTES = 512 * 1024;
+const ALLOWED_MEDIA_TYPES = new Set([
+  "application/json",
+  "application/xml",
+  "application/xhtml+xml",
+  "text/html",
+  "text/plain",
+  "text/xml",
+]);
+
+function exactSourceError(code) {
+  return Object.assign(new Error(code), { code });
+}
+
+export function exactSourceToolAllowlist(profile) {
+  const governedToolNames = Array.isArray(profile?.directToolNames)
+    ? profile.directToolNames.filter((name) => typeof name === "string" && name)
+    : [];
+  return [...new Set([...governedToolNames, EXACT_SOURCE_READ_TOOL_NAME])];
+}
+
+function normalizeText(body, mediaType) {
+  let value = body.toString("utf8");
+  if (mediaType === "text/html" || mediaType === "application/xhtml+xml") {
+    value = value
+      .replace(/<(?:script|style|noscript|template)\b[^>]*>[\s\S]*?<\/(?:script|style|noscript|template)>/giu, " ")
+      .replace(/<[^>]+>/gu, " ")
+      .replace(/&nbsp;/giu, " ")
+      .replace(/&amp;/giu, "&")
+      .replace(/&lt;/giu, "<")
+      .replace(/&gt;/giu, ">");
+  }
+  return value
+    .replace(/\r\n?/gu, "\n")
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/gu, "")
+    .replace(/[ \t]+/gu, " ")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+}
+
+function defaultRequestOnce({ url, addresses, signal }) {
+  return new Promise((resolve, reject) => {
+    const transport = url.protocol === "https:" ? https : http;
+    const selectedAddress = addresses[0];
+    const family = isIP(selectedAddress);
+    const request = transport.request(url, {
+      method: "GET",
+      headers: {
+        accept: "text/html, text/plain, application/json, application/xml;q=0.9",
+        "accept-encoding": "identity",
+        "user-agent": "MirrorX-Exact-Source-Reader/1.0",
+      },
+      lookup(_hostname, options, callback) {
+        if (options?.all === true) {
+          callback(null, [{ address: selectedAddress, family }]);
+          return;
+        }
+        callback(null, selectedAddress, family);
+      },
+      signal,
+    }, (response) => {
+      const declaredLength = Number(response.headers["content-length"] ?? 0);
+      if (Number.isFinite(declaredLength) && declaredLength > MAX_BYTES) {
+        request.destroy(exactSourceError("source_reader_oversize"));
+        return;
+      }
+      const chunks = [];
+      let bytes = 0;
+      response.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_BYTES) {
+          request.destroy(exactSourceError("source_reader_oversize"));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => resolve({
+        statusCode: response.statusCode ?? 0,
+        headers: response.headers,
+        body: Buffer.concat(chunks),
+      }));
+    });
+    request.setTimeout(15_000, () => request.destroy(exactSourceError("source_reader_timeout")));
+    request.on("error", reject);
+    request.end();
+  });
+}
+
+export async function readExactPublicSource(locator, options = {}) {
+  const initial = new URL(locator);
+  const expectedOrigin = initial.origin;
+  const networkScope = createPublicNetworkScope(options.lookup ? { lookup: options.lookup } : {});
+  const requestOnce = options.requestOnce ?? defaultRequestOnce;
+  let current = initial;
+  for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+    if (current.origin !== expectedOrigin) throw exactSourceError("source_reader_redirect_scope_forbidden");
+    const addresses = await networkScope.resolveNetworkAddresses(current.toString());
+    const response = await requestOnce({
+      url: current,
+      addresses,
+      signal: options.signal,
+    });
+    if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+      const location = Array.isArray(response.headers.location)
+        ? response.headers.location[0]
+        : response.headers.location;
+      if (!location || redirectCount === MAX_REDIRECTS) {
+        throw exactSourceError("source_reader_redirect_invalid");
+      }
+      current = new URL(location, current);
+      continue;
+    }
+    if (response.statusCode === 401 || response.statusCode === 403) {
+      throw exactSourceError("user_link_auth_required");
+    }
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      throw exactSourceError("source_unavailable");
+    }
+    const contentEncoding = String(response.headers["content-encoding"] ?? "identity").toLowerCase();
+    if (contentEncoding !== "identity") throw exactSourceError("source_reader_content_encoding_forbidden");
+    const mediaType = String(response.headers["content-type"] ?? "text/plain")
+      .split(";", 1)[0].trim().toLowerCase();
+    if (!ALLOWED_MEDIA_TYPES.has(mediaType)) throw exactSourceError("source_reader_content_type_forbidden");
+    const normalizedText = normalizeText(response.body, mediaType);
+    if (!normalizedText) throw exactSourceError("source_reader_empty");
+    return {
+      requestedUrl: initial.toString(),
+      finalUrl: current.toString(),
+      mediaType,
+      normalizedText,
+      truncated: false,
+    };
+  }
+  throw exactSourceError("source_reader_redirect_invalid");
+}
+
+export function registerExactSourceReadTool(pi, binding, options = {}) {
+  pi.registerTool({
+    name: EXACT_SOURCE_READ_TOOL_NAME,
+    label: "Read the frozen user source",
+    description: "Read the one exact user-provided URL frozen by the Server. This tool accepts no URL argument.",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    executionMode: "sequential",
+    execute: async (toolCallId, _params, signal) => {
+      const evidence = await readExactPublicSource(binding.locator, { ...options, signal });
+      const capturedAt = new Date().toISOString();
+      writeSync(1, `${JSON.stringify({
+        type: "amaster_web_evidence",
+        version: "runtime_web_evidence_v1",
+        evidence: {
+          toolCallId,
+          requestedUrl: evidence.requestedUrl,
+          finalUrl: evidence.finalUrl,
+          capturedAt,
+          mediaType: evidence.mediaType,
+          normalizedText: evidence.normalizedText,
+          truncated: evidence.truncated,
+        },
+      })}\n`);
+      return {
+        content: [{ type: "text", text: evidence.normalizedText }],
+        details: {
+          requestedUrl: evidence.requestedUrl,
+          finalUrl: evidence.finalUrl,
+          capturedAt,
+          mediaType: evidence.mediaType,
+          contentSha256: createHash("sha256").update(evidence.normalizedText).digest("hex"),
+        },
+      };
+    },
+  });
+}
+
+export function managedPiExactSourceReadExtensionSource(binding, options = {}) {
+  const runtimeModuleUrl = typeof options.runtimeModuleUrl === "string" && options.runtimeModuleUrl
+    ? options.runtimeModuleUrl
+    : import.meta.url;
+  // Source tests resolve back to this module. The bundled daemon resolves to
+  // the side-effect-free dist sidecar copied by scripts/build.mjs. Never import
+  // the daemon entry itself from a Pi extension: doing so executes its CLI main.
+  const readerModuleUrl = new URL("./pi-exact-source-read.mjs", runtimeModuleUrl).href;
+  return `import { registerExactSourceReadTool } from ${JSON.stringify(readerModuleUrl)};\n`
+    + `const binding = ${JSON.stringify(binding)};\n`
+    + "export default function amasterExactSourceRead(pi) { registerExactSourceReadTool(pi, binding); }\n";
+}
+
+export function materializePiExactSourceReadExtension(profileRoot, binding) {
+  const extensionPath = join(profileRoot, "extensions", "amaster-exact-source-read.js");
+  mkdirSync(dirname(extensionPath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${extensionPath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporaryPath, managedPiExactSourceReadExtensionSource(binding), {
+      encoding: "utf8",
+      mode: 0o600,
+      flag: "wx",
+    });
+    renameSync(temporaryPath, extensionPath);
+    chmodSync(extensionPath, 0o600);
+    return extensionPath;
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}

package/dist/public-network-scope.mjs

@@ -0,0 +1,120 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+
+const blockedV4Addresses = new BlockList();
+for (const [network, prefix] of [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.88.99.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+]) {
+  blockedV4Addresses.addSubnet(network, prefix, "ipv4");
+}
+const blockedV6Addresses = new BlockList();
+for (const [network, prefix] of [
+  ["::", 128],
+  ["::1", 128],
+  ["::", 96],
+  ["::ffff:0:0", 96],
+  ["64:ff9b::", 96],
+  ["64:ff9b:1::", 48],
+  ["100::", 64],
+  ["2001::", 32],
+  ["2001:2::", 48],
+  ["2001:db8::", 32],
+  ["2001:10::", 28],
+  ["2001:20::", 28],
+  ["2002::", 16],
+  ["fc00::", 7],
+  ["fe80::", 10],
+  ["fec0::", 10],
+  ["ff00::", 8],
+]) {
+  blockedV6Addresses.addSubnet(network, prefix, "ipv6");
+}
+
+function forbidden() {
+  return Object.assign(new Error("source_reader_network_scope_forbidden"), {
+    code: "source_reader_network_scope_forbidden",
+  });
+}
+
+function parsePublicLocator(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw forbidden();
+  }
+  if (
+    (url.protocol !== "https:" && url.protocol !== "http:")
+    || url.username
+    || url.password
+    || !url.hostname
+  ) {
+    throw forbidden();
+  }
+  const hostname = url.hostname.toLowerCase().replace(/\.$/u, "");
+  if (
+    hostname === "localhost"
+    || hostname.endsWith(".localhost")
+    || hostname.endsWith(".local")
+  ) {
+    throw forbidden();
+  }
+  return { url, hostname };
+}
+
+function addressIsPublic(address) {
+  const family = isIP(address);
+  if (family === 4) return !blockedV4Addresses.check(address, "ipv4");
+  if (family === 6) return !blockedV6Addresses.check(address, "ipv6");
+  return false;
+}
+
+export function createPublicNetworkScope(options = {}) {
+  const lookup = options.lookup ?? ((hostname) => dnsLookup(hostname, {
+    all: true,
+    verbatim: true,
+  }));
+  async function resolveNetworkAddresses(locator) {
+    const { hostname } = parsePublicLocator(locator);
+    let addresses;
+    try {
+      addresses = await lookup(hostname);
+    } catch {
+      throw forbidden();
+    }
+    if (
+      !Array.isArray(addresses)
+      || addresses.length === 0
+      || addresses.some((entry) => (
+        !entry
+        || typeof entry.address !== "string"
+        || !addressIsPublic(entry.address)
+      ))
+    ) {
+      throw forbidden();
+    }
+    return [...new Set(addresses.map((entry) => entry.address))].sort();
+  }
+
+  return Object.freeze({
+    resolveNetworkAddresses,
+    async assertNetworkAddressAllowed(locator) {
+      await resolveNetworkAddresses(locator);
+      return true;
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/employee-runtime-connector",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "MirrorX runtime connector CLI and daemon",
   "license": "MIT",
   "type": "module",