@latchagent/latchctl 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @latchagent/latchctl
+
+Bootstrap and operate Latch integrations from the terminal.
+
+## Install
+
+```bash
+npm install -g @latchagent/latchctl
+```
+
+## OpenClaw Setup (One Command)
+
+```bash
+latchctl openclaw setup \
+  --cloud-url https://your-latch-url.com \
+  --workspace-id ws_xxx \
+  --upstream-id upstream_xxx \
+  --agent-key sk-latch-xxx
+```
+
+This command installs and enables `@latchagent/openclaw-latch-guard`, writes OpenClaw plugin config, and restarts gateway service.
+
+## Print Manual Commands
+
+```bash
+latchctl openclaw print-config \
+  --cloud-url https://your-latch-url.com \
+  --workspace-id ws_xxx \
+  --upstream-id upstream_xxx \
+  --agent-key sk-latch-xxx
+```
+
+## Authorize Test
+
+```bash
+latchctl openclaw test \
+  --cloud-url https://your-latch-url.com \
+  --workspace-id ws_xxx \
+  --upstream-id upstream_xxx \
+  --agent-key sk-latch-xxx \
+  --tool-name openclaw:read \
+  --action-class read \
+  --risk-level low
+```

package/index.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import readline from 'node:readline/promises';
+import process from 'node:process';
+
+const VERSION = '0.1.0';
+const DEFAULT_PLUGIN_SPEC = '@latchagent/openclaw-latch-guard@latest';
+const DEFAULT_PLUGIN_ID = 'openclaw-latch-guard';
+
+function printUsage() {
+  console.log(`
+latchctl v${VERSION}
+
+Usage:
+  latchctl openclaw setup [options]
+  latchctl openclaw print-config [options]
+  latchctl openclaw test [options]
+  latchctl help
+
+Commands:
+  openclaw setup        Install + configure Latch Guard for OpenClaw
+  openclaw print-config Print exact OpenClaw commands for manual setup
+  openclaw test         Send a direct authorize test request
+
+Global:
+  --help                Show command help
+  --non-interactive     Do not prompt for missing values
+`);
+}
+
+function printOpenclawUsage() {
+  console.log(`
+openclaw commands:
+
+  latchctl openclaw setup [options]
+    --cloud-url <url>                     Latch URL (env: LATCH_CLOUD_URL)
+    --workspace-id <id>                   Workspace ID (env: LATCH_WORKSPACE_ID)
+    --upstream-id <id>                    Connector ID (env: LATCH_UPSTREAM_ID)
+    --agent-key <key>                     Agent key (env: LATCH_AGENT_KEY)
+    --plugin-spec <spec>                  Plugin npm spec (default: ${DEFAULT_PLUGIN_SPEC})
+    --plugin-id <id>                      Plugin id (default: ${DEFAULT_PLUGIN_ID})
+    --mode <monitor|enforce>              Plugin mode (default: enforce)
+    --wait-for-approval <true|false>      Default: true
+    --approval-timeout-seconds <n>        Default: 600
+    --fail-closed <true|false>            Default: true
+    --log-file <path>                     Optional plugin log file
+    --openclaw-bin <bin>                  Default: openclaw
+    --skip-install <true|false>           Default: false
+    --skip-enable <true|false>            Default: false
+    --skip-restart <true|false>           Default: false
+    --dry-run <true|false>                Default: false
+    --non-interactive                     Do not prompt for missing values
+
+  latchctl openclaw print-config [options]
+    Same input options as setup. Prints manual commands only.
+
+  latchctl openclaw test [options]
+    --cloud-url <url>                     Latch URL
+    --workspace-id <id>                   Workspace ID
+    --upstream-id <id>                    Connector ID
+    --agent-key <key>                     Agent key
+    --tool-name <name>                    Default: openclaw:read
+    --action-class <class>                Default: read
+    --risk-level <level>                  Default: low
+    --args-json <json>                    Default: {}
+    --approval-token <token>              Optional approval token for retry
+    --require-allowed <true|false>        Exit non-zero if not allowed
+`);
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+
+    const withoutPrefix = token.slice(2);
+    const eqIndex = withoutPrefix.indexOf('=');
+    if (eqIndex >= 0) {
+      const key = withoutPrefix.slice(0, eqIndex);
+      const value = withoutPrefix.slice(eqIndex + 1);
+      flags[key] = value;
+      continue;
+    }
+
+    const key = withoutPrefix;
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    index += 1;
+  }
+
+  return { flags, positionals };
+}
+
+function parseBoolean(raw, fallback) {
+  if (raw === undefined) return fallback;
+  if (typeof raw === 'boolean') return raw;
+
+  const value = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(value)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(value)) return false;
+  throw new Error(`Invalid boolean value: ${raw}`);
+}
+
+function parseInteger(raw, fallback) {
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`Invalid numeric value: ${raw}`);
+  }
+  return Math.floor(parsed);
+}
+
+function canonicalize(input) {
+  if (Array.isArray(input)) return input.map(canonicalize);
+  if (input && typeof input === 'object') {
+    const entries = Object.entries(input).sort(([a], [b]) => a.localeCompare(b));
+    const out = {};
+    for (const [key, value] of entries) out[key] = canonicalize(value);
+    return out;
+  }
+  return input;
+}
+
+function hashJson(value) {
+  return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+}
+
+function quote(arg) {
+  if (/^[a-zA-Z0-9_./:@=-]+$/.test(arg)) return arg;
+  return JSON.stringify(arg);
+}
+
+function commandToString(bin, args) {
+  return [bin, ...args].map((part) => quote(String(part))).join(' ');
+}
+
+function runCommand({ bin, args, dryRun, allowFailure = false, display }) {
+  const rendered = display ?? commandToString(bin, args);
+  console.log(`\n$ ${rendered}`);
+  if (dryRun) return;
+
+  const result = spawnSync(bin, args, {
+    stdio: 'inherit',
+    shell: false,
+  });
+
+  if (result.error) {
+    if (allowFailure) {
+      console.warn(`Warning: command failed (${result.error.message})`);
+      return;
+    }
+    throw result.error;
+  }
+
+  if ((result.status ?? 0) !== 0) {
+    if (allowFailure) {
+      console.warn(`Warning: command exited with status ${result.status}`);
+      return;
+    }
+    throw new Error(`Command failed with status ${result.status}: ${rendered}`);
+  }
+}
+
+async function promptIfMissing(values, nonInteractive) {
+  if (nonInteractive || !process.stdin.isTTY || !process.stdout.isTTY) {
+    return values;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const next = { ...values };
+    if (!next.cloudUrl) {
+      const answer = await rl.question('Latch Cloud URL: ');
+      next.cloudUrl = answer.trim();
+    }
+    if (!next.workspaceId) {
+      const answer = await rl.question('Workspace ID (ws_...): ');
+      next.workspaceId = answer.trim();
+    }
+    if (!next.upstreamId) {
+      const answer = await rl.question('Connector ID / upstream_id: ');
+      next.upstreamId = answer.trim();
+    }
+    if (!next.agentKey) {
+      const answer = await rl.question('Agent key (sk-latch-...): ');
+      next.agentKey = answer.trim();
+    }
+    return next;
+  } finally {
+    rl.close();
+  }
+}
+
+function assertRequired(values) {
+  const missing = [];
+  if (!values.cloudUrl) missing.push('--cloud-url');
+  if (!values.workspaceId) missing.push('--workspace-id');
+  if (!values.upstreamId) missing.push('--upstream-id');
+  if (!values.agentKey) missing.push('--agent-key');
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required options: ${missing.join(', ')}`);
+  }
+}
+
+function buildSetupInput(flags) {
+  return {
+    cloudUrl: String(flags['cloud-url'] ?? process.env.LATCH_CLOUD_URL ?? '').trim(),
+    workspaceId: String(flags['workspace-id'] ?? process.env.LATCH_WORKSPACE_ID ?? '').trim(),
+    upstreamId: String(flags['upstream-id'] ?? process.env.LATCH_UPSTREAM_ID ?? '').trim(),
+    agentKey: String(flags['agent-key'] ?? process.env.LATCH_AGENT_KEY ?? '').trim(),
+    pluginSpec: String(flags['plugin-spec'] ?? process.env.LATCH_OPENCLAW_PLUGIN_SPEC ?? DEFAULT_PLUGIN_SPEC).trim(),
+    pluginId: String(flags['plugin-id'] ?? process.env.LATCH_OPENCLAW_PLUGIN_ID ?? DEFAULT_PLUGIN_ID).trim(),
+    mode: String(flags.mode ?? 'enforce').trim() || 'enforce',
+    waitForApproval: parseBoolean(flags['wait-for-approval'], true),
+    approvalTimeoutSeconds: parseInteger(flags['approval-timeout-seconds'], 600),
+    failClosed: parseBoolean(flags['fail-closed'], true),
+    logFile: String(flags['log-file'] ?? '').trim(),
+    openclawBin: String(flags['openclaw-bin'] ?? process.env.OPENCLAW_BIN ?? 'openclaw').trim() || 'openclaw',
+    skipInstall: parseBoolean(flags['skip-install'], false),
+    skipEnable: parseBoolean(flags['skip-enable'], false),
+    skipRestart: parseBoolean(flags['skip-restart'], false),
+    dryRun: parseBoolean(flags['dry-run'], false),
+    nonInteractive: parseBoolean(flags['non-interactive'], false),
+  };
+}
+
+function buildManualSetupCommands(input) {
+  const base = `plugins.entries.${input.pluginId}.config`;
+  return [
+    `${input.openclawBin} plugins install ${input.pluginSpec}`,
+    `${input.openclawBin} plugins enable ${input.pluginId}`,
+    `${input.openclawBin} config set ${base}.baseUrl ${JSON.stringify(input.cloudUrl)}`,
+    `${input.openclawBin} config set ${base}.workspaceId ${JSON.stringify(input.workspaceId)}`,
+    `${input.openclawBin} config set ${base}.upstreamId ${JSON.stringify(input.upstreamId)}`,
+    `${input.openclawBin} config set ${base}.agentKey ${JSON.stringify(input.agentKey)}`,
+    `${input.openclawBin} config set ${base}.mode ${JSON.stringify(input.mode)}`,
+    `${input.openclawBin} config set ${base}.waitForApproval ${JSON.stringify(input.waitForApproval)} --json`,
+    `${input.openclawBin} config set ${base}.approvalTimeoutSeconds ${JSON.stringify(input.approvalTimeoutSeconds)} --json`,
+    `${input.openclawBin} config set ${base}.failClosed ${JSON.stringify(input.failClosed)} --json`,
+    ...(input.logFile ? [`${input.openclawBin} config set ${base}.logFile ${JSON.stringify(input.logFile)}`] : []),
+    `${input.openclawBin} gateway restart`,
+  ];
+}
+
+async function runOpenclawSetup(flags) {
+  let input = buildSetupInput(flags);
+  input = await promptIfMissing(input, input.nonInteractive);
+  assertRequired(input);
+
+  if (!['monitor', 'enforce'].includes(input.mode)) {
+    throw new Error('--mode must be monitor or enforce');
+  }
+
+  const base = `plugins.entries.${input.pluginId}.config`;
+
+  const commands = [];
+  if (!input.skipInstall) {
+    commands.push({
+      bin: input.openclawBin,
+      args: ['plugins', 'install', input.pluginSpec],
+    });
+  }
+  if (!input.skipEnable) {
+    commands.push({
+      bin: input.openclawBin,
+      args: ['plugins', 'enable', input.pluginId],
+    });
+  }
+
+  commands.push(
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.baseUrl`, input.cloudUrl],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.workspaceId`, input.workspaceId],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.upstreamId`, input.upstreamId],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.agentKey`, input.agentKey],
+      display: `${input.openclawBin} config set ${base}.agentKey "<redacted>"`,
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.mode`, input.mode],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.waitForApproval`, String(input.waitForApproval), '--json'],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.approvalTimeoutSeconds`, String(input.approvalTimeoutSeconds), '--json'],
+    },
+    {
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.failClosed`, String(input.failClosed), '--json'],
+    },
+  );
+
+  if (input.logFile) {
+    commands.push({
+      bin: input.openclawBin,
+      args: ['config', 'set', `${base}.logFile`, input.logFile],
+    });
+  }
+
+  if (!input.skipRestart) {
+    commands.push({
+      bin: input.openclawBin,
+      args: ['gateway', 'restart'],
+      allowFailure: true,
+    });
+  }
+
+  commands.push({
+    bin: input.openclawBin,
+    args: ['plugins', 'info', input.pluginId],
+    allowFailure: true,
+  });
+
+  console.log('\nConfiguring OpenClaw with Latch Guard...');
+  for (const command of commands) {
+    runCommand({
+      ...command,
+      dryRun: input.dryRun,
+    });
+  }
+
+  console.log('\nOpenClaw setup complete.');
+  if (input.dryRun) {
+    console.log('Dry-run mode: no commands were executed.');
+  }
+}
+
+async function runOpenclawPrintConfig(flags) {
+  let input = buildSetupInput(flags);
+  input = await promptIfMissing(input, input.nonInteractive);
+  assertRequired(input);
+
+  console.log('\n# Manual OpenClaw setup commands');
+  for (const command of buildManualSetupCommands(input)) {
+    if (command.includes('.agentKey')) {
+      console.log(command.replace(input.agentKey, '<paste-agent-key>'));
+    } else {
+      console.log(command);
+    }
+  }
+  console.log('\n# Replace <paste-agent-key> only if redacted in output.');
+}
+
+function buildTestInput(flags) {
+  return {
+    cloudUrl: String(flags['cloud-url'] ?? process.env.LATCH_CLOUD_URL ?? '').trim(),
+    workspaceId: String(flags['workspace-id'] ?? process.env.LATCH_WORKSPACE_ID ?? '').trim(),
+    upstreamId: String(flags['upstream-id'] ?? process.env.LATCH_UPSTREAM_ID ?? '').trim(),
+    agentKey: String(flags['agent-key'] ?? process.env.LATCH_AGENT_KEY ?? '').trim(),
+    toolName: String(flags['tool-name'] ?? 'openclaw:read').trim(),
+    actionClass: String(flags['action-class'] ?? 'read').trim(),
+    riskLevel: String(flags['risk-level'] ?? 'low').trim(),
+    argsJson: String(flags['args-json'] ?? '{}'),
+    approvalToken: String(flags['approval-token'] ?? '').trim(),
+    requireAllowed: parseBoolean(flags['require-allowed'], false),
+    nonInteractive: parseBoolean(flags['non-interactive'], false),
+  };
+}
+
+async function runOpenclawTest(flags) {
+  let input = buildTestInput(flags);
+  input = await promptIfMissing(input, input.nonInteractive);
+  assertRequired(input);
+
+  let parsedArgs;
+  try {
+    parsedArgs = JSON.parse(input.argsJson);
+  } catch (error) {
+    throw new Error(`--args-json must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const argsRedacted = parsedArgs && typeof parsedArgs === 'object' ? parsedArgs : {};
+  const argsHash = hashJson(argsRedacted);
+  const requestHash = hashJson({
+    tool_name: input.toolName,
+    action_class: input.actionClass,
+    risk_level: input.riskLevel,
+    args: argsRedacted,
+  });
+
+  const body = {
+    workspace_id: input.workspaceId,
+    agent_key: input.agentKey,
+    upstream_id: input.upstreamId,
+    tool_name: input.toolName,
+    action_class: input.actionClass,
+    risk_level: input.riskLevel,
+    risk_flags: {
+      external_domain: false,
+      new_recipient: false,
+      attachment: false,
+      form_submit: false,
+      shell_exec: input.actionClass === 'execute',
+      destructive: input.riskLevel === 'high' && input.actionClass === 'execute',
+    },
+    resource: {},
+    args_hash: argsHash,
+    request_hash: requestHash,
+    args_redacted: argsRedacted,
+    ...(input.approvalToken ? { approval_token: input.approvalToken } : {}),
+  };
+
+  const url = `${input.cloudUrl.replace(/\/$/, '')}/api/v1/authorize`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Latch-Agent-Key': input.agentKey,
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+
+  console.log(`\nPOST ${url}`);
+  console.log(`status: ${response.status}`);
+  console.log(JSON.stringify(data, null, 2));
+
+  if (!response.ok) {
+    process.exit(1);
+  }
+
+  if (input.requireAllowed && data?.decision !== 'allowed') {
+    process.exit(2);
+  }
+}
+
+async function runOpenclawCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+    printOpenclawUsage();
+    return;
+  }
+
+  const { flags } = parseArgs(rest);
+
+  if (subcommand === 'setup') {
+    await runOpenclawSetup(flags);
+    return;
+  }
+  if (subcommand === 'print-config') {
+    await runOpenclawPrintConfig(flags);
+    return;
+  }
+  if (subcommand === 'test') {
+    await runOpenclawTest(flags);
+    return;
+  }
+
+  throw new Error(`Unknown openclaw subcommand: ${subcommand}`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const [command] = argv;
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printUsage();
+    return;
+  }
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(VERSION);
+    return;
+  }
+  if (command === 'openclaw') {
+    await runOpenclawCommand(argv.slice(1));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@latchagent/latchctl",
+  "version": "0.1.0",
+  "description": "Latch CLI bootstrap tool for OpenClaw and runtime configuration.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/latchagent/latch-marketing-site.git",
+    "directory": "packages/latchctl"
+  },
+  "bugs": {
+    "url": "https://github.com/latchagent/latch-marketing-site/issues"
+  },
+  "homepage": "https://github.com/latchagent/latch-marketing-site/tree/main/packages/latchctl",
+  "keywords": [
+    "latch",
+    "openclaw",
+    "security",
+    "governance",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "latchctl": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}