@myagentroam/marctl 0.9.120

package/src/client.mjs

@@ -0,0 +1,220 @@
+import { MarctlError } from './config.mjs';
+import { createTranslator } from './i18n/index.mjs';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+
+export class MarctlClient {
+  #serverUrl;
+  #key;
+  #fetch;
+  #translate;
+  #requestTimeoutMs;
+
+  constructor({
+    serverUrl,
+    key,
+    fetchImpl = globalThis.fetch,
+    translate = createTranslator(),
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+  }) {
+    this.#serverUrl = serverUrl;
+    this.#key = key;
+    this.#fetch = fetchImpl;
+    this.#translate = translate;
+    this.#requestTimeoutMs = requestTimeoutMs;
+    if (typeof this.#fetch !== 'function')
+      throw new MarctlError(this.#translate('errors.fetchUnavailable'));
+  }
+
+  async listNodes() {
+    const payload = await this.#requestJson('/api/marctl/nodes');
+    if (!isRecord(payload) || !Array.isArray(payload.nodes))
+      throw new MarctlError(this.#translate('errors.serverInvalidNodes'));
+
+    return payload.nodes.map((node) => {
+      if (
+        !isRecord(node) ||
+        !isNonEmptyString(node.id) ||
+        typeof node.connected !== 'boolean' ||
+        (node.displayName !== undefined && typeof node.displayName !== 'string') ||
+        (node.platform !== undefined && typeof node.platform !== 'string')
+      )
+        throw new MarctlError(this.#translate('errors.serverInvalidNodes'));
+      return {
+        id: node.id,
+        ...(node.displayName === undefined ? {} : { displayName: node.displayName }),
+        connected: node.connected,
+        ...(node.platform === undefined ? {} : { platform: node.platform })
+      };
+    });
+  }
+
+  async createTerminal({ nodeId, rows, cols, command, binary = false }) {
+    validateNodeId(nodeId, this.#translate);
+    validateDimensions(rows, cols, this.#translate);
+    if (command !== undefined && typeof command !== 'string')
+      throw new MarctlError(this.#translate('errors.terminalCommandInvalid'));
+    const body = { nodeId, rows, cols };
+    if (command !== undefined) body.command = command;
+    if (binary) body.binary = true;
+    const payload = await this.#requestJson('/api/marctl/terminals', {
+      method: 'POST',
+      body
+    });
+    if (!isRecord(payload) || !isNonEmptyString(payload.terminalId))
+      throw new MarctlError(this.#translate('errors.serverInvalidTerminalId'));
+    return binary
+      ? { terminalId: payload.terminalId, binary: payload.binary === true }
+      : payload.terminalId;
+  }
+
+  async getTerminalManifest(nodeId) {
+    validateNodeId(nodeId, this.#translate);
+    const payload = await this.#requestJson(
+      `/api/marctl/nodes/${encodeURIComponent(nodeId)}/manifest`
+    );
+    if (
+      !isRecord(payload) ||
+      !isRecord(payload.manifest) ||
+      !isNonEmptyString(payload.manifest.nodeGeneration)
+    )
+      throw new MarctlError(this.#translate('errors.serverInvalidManifest'));
+    return {
+      ...payload.manifest,
+      ...(payload.deferredRelay === true ? { deferredRelay: true } : {}),
+      ...(payload.binaryTerminal === true ? { binaryTerminal: true } : {})
+    };
+  }
+
+  async createAttachTicket({ nodeId, terminalId, afterSequence }) {
+    validateNodeId(nodeId, this.#translate);
+    validateTerminalId(terminalId, this.#translate);
+    if (afterSequence !== undefined && (!Number.isSafeInteger(afterSequence) || afterSequence < 0))
+      throw new MarctlError(this.#translate('errors.terminalSequenceInvalid'));
+
+    const body = { nodeId };
+    if (afterSequence !== undefined) body.afterSequence = afterSequence;
+    const payload = await this.#requestJson(
+      `/api/marctl/terminals/${encodeURIComponent(terminalId)}/attach-ticket`,
+      { method: 'POST', body }
+    );
+    if (!isRecord(payload) || !isNonEmptyString(payload.ticket))
+      throw new MarctlError(this.#translate('errors.serverInvalidTicket'));
+    return payload.ticket;
+  }
+
+  async deleteTerminal({ nodeId, terminalId }) {
+    validateNodeId(nodeId, this.#translate);
+    validateTerminalId(terminalId, this.#translate);
+    await this.#request('/api/marctl/terminals/' + encodeURIComponent(terminalId), {
+      method: 'DELETE',
+      body: { nodeId }
+    });
+  }
+
+  openTerminalWebSocket(WebSocketClass, { terminalId, ticket, deferred = false }) {
+    validateTerminalId(terminalId, this.#translate);
+    if (!isNonEmptyString(ticket))
+      throw new MarctlError(this.#translate('errors.terminalTicketInvalid'));
+
+    const url = new URL(
+      `/api/marctl/terminals/${encodeURIComponent(terminalId)}/connect`,
+      `${this.#serverUrl}/`
+    );
+    url.searchParams.set('ticket', ticket);
+    if (deferred) url.searchParams.set('deferred', '1');
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+
+    try {
+      return new WebSocketClass(url.toString(), {
+        headers: { Authorization: `Bearer ${this.#key}` }
+      });
+    } catch {
+      throw new MarctlError(this.#translate('errors.terminalConnectionStart'));
+    }
+  }
+
+  openWorkbenchWebSocket(WebSocketClass) {
+    const url = new URL('/api/marctl/live', `${this.#serverUrl}/`);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    try {
+      return new WebSocketClass(url.toString(), {
+        headers: { Authorization: `Bearer ${this.#key}` }
+      });
+    } catch {
+      throw new MarctlError(this.#translate('errors.workbenchConnectionStart'));
+    }
+  }
+
+  async #requestJson(pathname, options = {}) {
+    return this.#request(pathname, { ...options, json: true });
+  }
+
+  async #request(pathname, { method = 'GET', body, json = false } = {}) {
+    const headers = {
+      Accept: 'application/json',
+      Authorization: `Bearer ${this.#key}`
+    };
+    const controller = new AbortController();
+    const request = { method, headers, signal: controller.signal };
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      request.body = JSON.stringify(body);
+    }
+
+    const timer = setTimeout(() => controller.abort(), this.#requestTimeoutMs);
+    try {
+      const response = await this.#fetch(new URL(pathname, `${this.#serverUrl}/`), request);
+      if (!response?.ok) throw new MarctlError(this.#translate('errors.serverRejected'));
+      if (!json) return response;
+      try {
+        return await response.json();
+      } catch {
+        throw new MarctlError(
+          this.#translate(
+            controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverInvalidJson'
+          )
+        );
+      }
+    } catch (error) {
+      if (error instanceof MarctlError) throw error;
+      throw new MarctlError(
+        this.#translate(
+          controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverUnreachable'
+        )
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function validateNodeId(nodeId, translate) {
+  if (!isNonEmptyString(nodeId) || nodeId.length > 128)
+    throw new MarctlError(translate('errors.nodeIdInvalid'));
+}
+
+function validateTerminalId(terminalId, translate) {
+  if (!isNonEmptyString(terminalId) || terminalId.length > 128)
+    throw new MarctlError(translate('errors.terminalIdInvalid'));
+}
+
+function validateDimensions(rows, cols, translate) {
+  if (
+    !Number.isSafeInteger(rows) ||
+    !Number.isSafeInteger(cols) ||
+    rows < 1 ||
+    cols < 1 ||
+    rows > 1000 ||
+    cols > 1000
+  )
+    throw new MarctlError(translate('errors.terminalSizeInvalid'));
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}

package/src/config.mjs

@@ -0,0 +1,164 @@
+import { lstat, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createTranslator } from './i18n/index.mjs';
+
+export const CONFIG_KEYS = Object.freeze(['MAR_CTL_SERVER_URL', 'MAR_CTL_KEY']);
+
+export class MarctlError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = 'MarctlError';
+  }
+}
+
+export function defaultConfigPath({
+  env = process.env,
+  platform = process.platform,
+  homeDirectory = os.homedir()
+} = {}) {
+  const configuredHome =
+    nonEmptyString(env.HOME) ??
+    (platform === 'win32' ? nonEmptyString(env.USERPROFILE) : undefined) ??
+    homeDirectory;
+  return path.join(configuredHome, '.marctl', 'default.env');
+}
+
+export async function loadConfig({
+  env = process.env,
+  envFile,
+  platform = process.platform,
+  homeDirectory = os.homedir(),
+  translate = createTranslator(env)
+} = {}) {
+  if (env.MAR_CTL_CONTEXT_REQUIRED === '1') {
+    const serverUrl = nonEmptyString(env.MAR_CTL_SERVER_URL);
+    const token = nonEmptyString(env.MAR_CTL_USER_TOKEN);
+    if (
+      serverUrl === undefined ||
+      token === undefined ||
+      !/^marctl_user_[A-Za-z0-9_-]{43}$/u.test(token)
+    )
+      throw new MarctlError(translate('errors.userContextUnavailable'));
+    return Object.freeze({
+      serverUrl: validateServerUrl(serverUrl, translate),
+      key: token
+    });
+  }
+  const configPath = envFile ?? defaultConfigPath({ env, platform, homeDirectory });
+  const values = await readConfigFile(configPath, { platform, translate });
+
+  const serverUrlValue = nonEmptyString(values.MAR_CTL_SERVER_URL);
+  if (serverUrlValue === undefined)
+    throw new MarctlError(translate('errors.configServerUrlMissing'));
+
+  const keyValue = nonEmptyString(values.MAR_CTL_KEY);
+  if (keyValue === undefined) throw new MarctlError(translate('errors.configKeyMissing'));
+  if (/[\u0000-\u001f\u007f]/u.test(keyValue))
+    throw new MarctlError(translate('errors.configKeyInvalid'));
+
+  return Object.freeze({
+    serverUrl: validateServerUrl(serverUrlValue, translate),
+    key: keyValue
+  });
+}
+
+export function validateServerUrl(value, translate = createTranslator()) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new MarctlError(translate('errors.serverUrlInvalid'));
+  }
+
+  const isLoopbackHttp =
+    url.protocol === 'http:' &&
+    (url.hostname === 'localhost' ||
+      url.hostname === '127.0.0.1' ||
+      url.hostname === '::1' ||
+      url.hostname === '[::1]');
+  if (url.protocol !== 'https:' && !isLoopbackHttp)
+    throw new MarctlError(translate('errors.serverUrlTransport'));
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+    throw new MarctlError(translate('errors.serverUrlOrigin'));
+
+  return url.origin;
+}
+
+async function readConfigFile(filePath, { platform, translate }) {
+  let before;
+  try {
+    before = await lstat(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new MarctlError(translate('errors.envFileMissing'));
+    throw new MarctlError(translate('errors.envFileRead'));
+  }
+  assertSecureConfigFile(before, platform, translate);
+
+  let content;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch {
+    throw new MarctlError(translate('errors.envFileRead'));
+  }
+
+  let after;
+  try {
+    after = await lstat(filePath);
+  } catch {
+    throw new MarctlError(translate('errors.envFileRead'));
+  }
+  assertSecureConfigFile(after, platform, translate);
+  if (before.dev !== after.dev || before.ino !== after.ino)
+    throw new MarctlError(translate('errors.envFileRead'));
+
+  const values = {};
+  for (const rawLine of content.replace(/^\uFEFF/u, '').split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (line === '' || line.startsWith('#')) continue;
+
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u.exec(line);
+    if (match === null) throw new MarctlError(translate('errors.envFileEntry'));
+
+    const [, name, rawValue] = match;
+    if (!CONFIG_KEYS.includes(name)) throw new MarctlError(translate('errors.envFileUnsupported'));
+    values[name] = parseEnvValue(rawValue, translate);
+  }
+  return values;
+}
+
+function parseEnvValue(rawValue, translate) {
+  const value = rawValue.trim();
+  if (value.startsWith('"') || value.startsWith("'")) {
+    const quote = value[0];
+    if (!value.endsWith(quote) || value.length < 2)
+      throw new MarctlError(translate('errors.envFileQuoted'));
+    const body = value.slice(1, -1);
+    if (quote === "'") return body;
+    return body.replace(/\\(["\\nrt])/gu, (_match, escaped) => {
+      if (escaped === 'n') return '\n';
+      if (escaped === 'r') return '\r';
+      if (escaped === 't') return '\t';
+      return escaped;
+    });
+  }
+  return value;
+}
+
+function assertSecureConfigFile(stats, platform, translate) {
+  if (stats.isSymbolicLink()) throw new MarctlError(translate('errors.envFileSymlink'));
+  if (!stats.isFile()) throw new MarctlError(translate('errors.envFileType'));
+  if (platform === 'win32') return;
+
+  const permissions = stats.mode & 0o7777;
+  const ownerUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+  if (
+    (ownerUid !== undefined && stats.uid !== ownerUid) ||
+    (permissions !== 0o600 && permissions !== 0o400)
+  )
+    throw new MarctlError(translate('errors.envFilePermissions'));
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}