@4xeoz/re-entry 0.2.0

package/src/credentials.mjs

@@ -0,0 +1,87 @@
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+const CREDENTIAL_FIELDS = Object.freeze([
+  "version",
+  "receiver_origin",
+  "connector_id",
+  "connector_token",
+  "connector_expires_at",
+]);
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+export class LocalConnectorCredentialStore {
+  #filename;
+
+  constructor(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options) || typeof options.filename !== "string" || options.filename.length === 0) {
+      throw new TypeError("Credential store requires a filename");
+    }
+    this.#filename = options.filename;
+  }
+
+  async load() {
+    let value;
+    try {
+      value = JSON.parse(await readFile(this.#filename, "utf8"));
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw credentialFailure("connector_credentials_unreadable", "Connector credentials could not be read", error);
+    }
+    return normalizeCredentials(value);
+  }
+
+  async save(value) {
+    const normalized = normalizeCredentials(value);
+    await mkdir(dirname(this.#filename), { recursive: true, mode: 0o700 });
+    const temporary = `${this.#filename}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify(normalized)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+      await chmod(temporary, 0o600);
+      await rename(temporary, this.#filename);
+      await chmod(this.#filename, 0o600);
+    } catch (error) {
+      await unlink(temporary).catch(() => {});
+      throw credentialFailure("connector_credentials_unwritable", "Connector credentials could not be stored", error);
+    }
+  }
+}
+
+function normalizeCredentials(value) {
+  requireExactRecord(value, CREDENTIAL_FIELDS, CREDENTIAL_FIELDS, "Connector credentials");
+  if (value.version !== 1) throw credentialFailure("connector_credentials_invalid", "Connector credential version is unsupported");
+  if (
+    typeof value.receiver_origin !== "string" ||
+    !/^https?:\/\/[^/]+$/.test(value.receiver_origin) ||
+    (value.receiver_origin.startsWith("http://") && !/http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?$/.test(value.receiver_origin))
+  ) {
+    throw credentialFailure("connector_credentials_invalid", "Connector receiver origin is invalid");
+  }
+  if (typeof value.connector_id !== "string" || !IDENTIFIER_PATTERN.test(value.connector_id)) {
+    throw credentialFailure("connector_credentials_invalid", "Connector ID is invalid");
+  }
+  if (typeof value.connector_token !== "string" || !TOKEN_PATTERN.test(value.connector_token)) {
+    throw credentialFailure("connector_credentials_invalid", "Connector token is invalid");
+  }
+  const expires = Date.parse(value.connector_expires_at);
+  if (typeof value.connector_expires_at !== "string" || !Number.isFinite(expires) || new Date(expires).toISOString() !== value.connector_expires_at) {
+    throw credentialFailure("connector_credentials_invalid", "Connector credential expiry is invalid");
+  }
+  return Object.freeze({ ...value });
+}
+
+function requireExactRecord(value, allowedFields, requiredFields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw credentialFailure("connector_credentials_invalid", `${label} must be an object`);
+  const fields = Object.keys(value);
+  if (fields.some((field) => !allowedFields.includes(field)) || requiredFields.some((field) => !fields.includes(field))) {
+    throw credentialFailure("connector_credentials_invalid", `${label} fields are invalid`);
+  }
+}
+
+function credentialFailure(code, message, cause) {
+  const error = new Error(`${code}: ${message}`, cause === undefined ? undefined : { cause });
+  error.code = code;
+  return error;
+}

package/src/index.mjs

@@ -0,0 +1,6 @@
+export * from "./credentials.mjs";
+export * from "./codex-discovery.mjs";
+export * from "./codex-exec-adapter.mjs";
+export * from "./local-connector.mjs";
+export * from "./pairing-client.mjs";
+export * from "./terminal-ui.mjs";

package/src/local-connector.mjs

@@ -0,0 +1,82 @@
+import { randomBytes } from "node:crypto";
+
+import {
+  dispatchAgentActivation,
+} from "@webmcp-challenge/reentry-core/agent-adapter";
+import { LocalConnectorClient } from "@webmcp-challenge/reentry-core/local-connector-client";
+
+const OPTION_FIELDS = Object.freeze([
+  "client",
+  "adapter",
+  "clock",
+  "activationTimeoutMs",
+  "createClaimToken",
+]);
+const MIN_TIMEOUT_MS = 100;
+const MAX_TIMEOUT_MS = 60_000;
+
+export class LocalConnector {
+  #client;
+  #adapter;
+  #clock;
+  #activationTimeoutMs;
+  #createClaimToken;
+
+  constructor(options) {
+    requireExactRecord(options, OPTION_FIELDS, OPTION_FIELDS, "Local Connector options");
+    if (!(options.client instanceof LocalConnectorClient)) {
+      throw new TypeError("Local Connector client must be a LocalConnectorClient");
+    }
+    if (!options.adapter || typeof options.adapter.activate !== "function") {
+      throw new TypeError("Local Connector adapter must implement activate");
+    }
+    if (typeof options.clock !== "function") throw new TypeError("Local Connector clock must be a function");
+    if (!Number.isSafeInteger(options.activationTimeoutMs) || options.activationTimeoutMs < MIN_TIMEOUT_MS || options.activationTimeoutMs > MAX_TIMEOUT_MS) {
+      throw new TypeError("Local Connector activationTimeoutMs is invalid");
+    }
+    if (typeof options.createClaimToken !== "function") throw new TypeError("Local Connector createClaimToken must be a function");
+    this.#client = options.client;
+    this.#adapter = options.adapter;
+    this.#clock = options.clock;
+    this.#activationTimeoutMs = options.activationTimeoutMs;
+    this.#createClaimToken = options.createClaimToken;
+  }
+
+  async runOnce() {
+    const claimToken = this.#createClaimToken();
+    const claim = await this.#client.claimDelivery({ claimToken });
+    if (claim === null) return Object.freeze({ status: "idle" });
+    const result = await dispatchAgentActivation({
+      adapter: this.#adapter,
+      lease: claim.lease,
+      now: this.#readClock(),
+      timeoutMs: this.#activationTimeoutMs,
+    });
+    return Object.freeze({
+      status: "activation_result",
+      delivery_id: claim.lease.delivery_id,
+      event_id: claim.lease.event_id,
+      result,
+    });
+  }
+
+  acknowledgeDelivery(input) {
+    return this.#client.acknowledgeDelivery(input);
+  }
+
+  #readClock() {
+    const value = this.#clock();
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new TypeError("Local Connector clock must return a valid Date");
+    return new Date(value.getTime());
+  }
+}
+
+export function createRandomClaimToken() {
+  return randomBytes(32).toString("base64url");
+}
+
+function requireExactRecord(value, allowedFields, requiredFields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be an object`);
+  const fields = Object.keys(value);
+  if (fields.some((field) => !allowedFields.includes(field)) || requiredFields.some((field) => !fields.includes(field))) throw new TypeError(`${label} fields are invalid`);
+}

package/src/macos-service.mjs

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import { access, chmod, mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+const LABEL = "com.reentry.local-connector";
+
+export async function installMacConnectorService(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw serviceFailure("connector_service_input_invalid", "Service installation options are invalid");
+  }
+  if (process.platform !== "darwin" && options.allowNonMacForTest !== true) {
+    throw serviceFailure("connector_service_platform_unsupported", "Background installation currently supports macOS only");
+  }
+  const nodeExecutable = requireAbsolutePath(options.nodeExecutable, "Node executable");
+  const entrypoint = requireAbsolutePath(options.entrypoint, "Connector entrypoint");
+  const workingDirectory = requireAbsolutePath(options.workingDirectory, "Codex working directory");
+  const credentialFile = requireAbsolutePath(options.credentialFile, "Credential file");
+  const launchAgentsDirectory = options.launchAgentsDirectory ?? join(homedir(), "Library", "LaunchAgents");
+  const stateDirectory = options.stateDirectory ?? join(homedir(), ".webmcp-connector");
+  const runCommand = options.runCommand ?? runLaunchctl;
+  if (typeof runCommand !== "function") {
+    throw new TypeError("Service installer runCommand must be a function");
+  }
+  const plistPath = join(launchAgentsDirectory, `${LABEL}.plist`);
+  const stdoutPath = join(stateDirectory, "connector.log");
+  const stderrPath = join(stateDirectory, "connector-error.log");
+  const plist = renderLaunchAgent({
+    nodeExecutable,
+    entrypoint,
+    workingDirectory,
+    credentialFile,
+    stdoutPath,
+    stderrPath,
+  });
+
+  await mkdir(launchAgentsDirectory, { recursive: true, mode: 0o700 });
+  await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
+  const temporary = `${plistPath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, plist, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(temporary, 0o600);
+    await rename(temporary, plistPath);
+    await chmod(plistPath, 0o600);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw serviceFailure("connector_service_write_failed", "Background service could not be installed", error);
+  }
+
+  if (options.load !== false) {
+    const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : 0}`;
+    await runCommand(["bootout", `${domain}/${LABEL}`]);
+    const result = await runCommand(["bootstrap", domain, plistPath]);
+    if (result.code !== 0) {
+      throw serviceFailure("connector_service_load_failed", "Background service file was written but could not be started");
+    }
+  }
+
+  return Object.freeze({
+    label: LABEL,
+    plistPath,
+    stdoutPath,
+    stderrPath,
+  });
+}
+
+export async function inspectMacConnectorService(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw serviceFailure("connector_service_input_invalid", "Service status options are invalid");
+  }
+  if (process.platform !== "darwin" && options.allowNonMacForTest !== true) {
+    return Object.freeze({ supported: false, installed: false, running: false });
+  }
+  const launchAgentsDirectory = options.launchAgentsDirectory ?? join(homedir(), "Library", "LaunchAgents");
+  const runCommand = options.runCommand ?? runLaunchctl;
+  if (typeof runCommand !== "function") {
+    throw new TypeError("Service status runCommand must be a function");
+  }
+  const plistPath = join(launchAgentsDirectory, `${LABEL}.plist`);
+  try {
+    await access(plistPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return Object.freeze({ supported: true, installed: false, running: false, plistPath });
+    }
+    throw serviceFailure("connector_service_status_failed", "Background service status is unavailable", error);
+  }
+  const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : 0}`;
+  const result = await runCommand(["print", `${domain}/${LABEL}`]);
+  return Object.freeze({
+    supported: true,
+    installed: true,
+    running: result.code === 0,
+    plistPath,
+  });
+}
+
+export function renderLaunchAgent(options) {
+  const argumentsList = [
+    options.nodeExecutable,
+    options.entrypoint,
+    "start",
+    "--credential-file",
+    options.credentialFile,
+    "--codex-cd",
+    options.workingDirectory,
+  ];
+  const argumentsXml = argumentsList.map((value) => `      <string>${escapeXml(value)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argumentsXml}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ProcessType</key>
+    <string>Background</string>
+    <key>WorkingDirectory</key>
+    <string>${escapeXml(options.workingDirectory)}</string>
+    <key>StandardOutPath</key>
+    <string>${escapeXml(options.stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(options.stderrPath)}</string>
+  </dict>
+</plist>
+`;
+}
+
+function runLaunchctl(argumentsList) {
+  return new Promise((resolve) => {
+    const child = spawn("launchctl", argumentsList, { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      if (stderr.length < 4_096) stderr += chunk;
+    });
+    child.once("error", (error) => finish({ code: -1, stderr: error.message }));
+    child.once("close", (code) => finish({ code: code ?? -1, stderr }));
+  });
+}
+
+function requireAbsolutePath(value, label) {
+  if (
+    typeof value !== "string" ||
+    !isAbsolute(value) ||
+    value.length > 4_096 ||
+    value.includes("\0")
+  ) {
+    throw serviceFailure("connector_service_path_invalid", `${label} is invalid`);
+  }
+  return value;
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function serviceFailure(code, message, cause) {
+  const error = new Error(message, cause === undefined ? undefined : { cause });
+  error.code = code;
+  return error;
+}