@sellable/install/lib/sellable-agent/fly-soul-bridge-exec.mjs

One-command installer for Sellable MCP in Claude Code, Codex, and Hermes

#!/usr/bin/env node

import {
  executeExternalSoulBridgeOperation,
  FlySoulBridgeError,
} from "./fly-soul-bridge.mjs";
import { SoulArtifactValidationError } from "./soul-artifact-validator.mjs";

export const FLY_SOUL_EXEC_TRANSPORT_MAX_BYTES = 128 * 1024 - 1;
const PROFILE_USER = "hermes";
const PROFILE_GROUP = "hermes";
const SHA256 = /^[a-f0-9]{64}$/;
const GENERATION = /^.{8,128}$/s;
const BASE64 =
  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
const BASE64URL = /^[A-Za-z0-9_-]+$/;

/**
 * @typedef {{
 *   getuid: () => number;
 *   getgid: () => number;
 *   initgroups: (user: string, extraGroup: string | number) => void;
 *   setgid: (id: string | number) => void;
 *   setuid: (id: string | number) => void;
 * }} FlySoulExecProcess
 */

function rejected() {
  throw new FlySoulBridgeError("soul_request_rejected");
}

function exactKeys(value, required, optional = []) {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const allowed = new Set([...required, ...optional]);
  return (
    required.every((key) => Object.hasOwn(value, key)) &&
    Object.keys(value).every((key) => allowed.has(key))
  );
}

function canonicalBase64(value) {
  if (typeof value !== "string" || !BASE64.test(value)) rejected();
  const bytes = Buffer.from(value, "base64");
  if (bytes.toString("base64") !== value) rejected();
  return bytes;
}

export function decodeFlySoulExecTransport(encoded) {
  if (
    typeof encoded !== "string" ||
    encoded.length < 1 ||
    Buffer.byteLength(encoded, "utf8") > FLY_SOUL_EXEC_TRANSPORT_MAX_BYTES ||
    !BASE64URL.test(encoded)
  ) {
    rejected();
  }
  const bytes = Buffer.from(encoded, "base64url");
  if (bytes.toString("base64url") !== encoded) rejected();
  let envelope;
  try {
    envelope = JSON.parse(bytes.toString("utf8"));
  } catch {
    rejected();
  }
  if (envelope.operation === "read") {
    if (!exactKeys(envelope, ["operation"], ["acknowledgedGeneration"])) {
      rejected();
    }
    if (
      envelope.acknowledgedGeneration !== undefined &&
      (typeof envelope.acknowledgedGeneration !== "string" ||
        !GENERATION.test(envelope.acknowledgedGeneration))
    ) {
      rejected();
    }
    return Object.freeze({
      operation: "read",
      ...(envelope.acknowledgedGeneration
        ? { acknowledgedGeneration: envelope.acknowledgedGeneration }
        : {}),
    });
  }
  if (envelope.operation === "save") {
    if (
      !exactKeys(
        envelope,
        ["operation", "contentBase64", "expectedRawFileSha256"],
        ["acknowledgedGeneration"]
      ) ||
      !SHA256.test(envelope.expectedRawFileSha256 ?? "") ||
      (envelope.acknowledgedGeneration !== undefined &&
        (typeof envelope.acknowledgedGeneration !== "string" ||
          !GENERATION.test(envelope.acknowledgedGeneration)))
    ) {
      rejected();
    }
    let content;
    try {
      content = new TextDecoder("utf-8", { fatal: true }).decode(
        canonicalBase64(envelope.contentBase64)
      );
    } catch (error) {
      if (error instanceof FlySoulBridgeError) throw error;
      rejected();
    }
    return Object.freeze({
      operation: "save",
      content,
      expectedRawFileSha256: envelope.expectedRawFileSha256,
      ...(envelope.acknowledgedGeneration
        ? { acknowledgedGeneration: envelope.acknowledgedGeneration }
        : {}),
    });
  }
  rejected();
}

/** @param {{ processImpl?: FlySoulExecProcess }} [input] */
export function dropFlySoulExecPrivileges({ processImpl = process } = {}) {
  if (
    typeof processImpl.getuid !== "function" ||
    typeof processImpl.getgid !== "function" ||
    typeof processImpl.initgroups !== "function" ||
    typeof processImpl.setgid !== "function" ||
    typeof processImpl.setuid !== "function" ||
    processImpl.getuid() !== 0 ||
    processImpl.getgid() !== 0
  ) {
    throw new FlySoulBridgeError("soul_exec_privilege_rejected");
  }
  processImpl.initgroups(PROFILE_USER, PROFILE_GROUP);
  processImpl.setgid(PROFILE_GROUP);
  processImpl.setuid(PROFILE_USER);
  if (processImpl.getuid() === 0 || processImpl.getgid() === 0) {
    throw new FlySoulBridgeError("soul_exec_privilege_rejected");
  }
}

export function executeFlySoulExecTransport(
  encoded,
  /** @type {{ processImpl?: FlySoulExecProcess; execute?: (request: any) => any }} */
  { processImpl = process, execute = executeExternalSoulBridgeOperation } = {}
) {
  const request = decodeFlySoulExecTransport(encoded);
  dropFlySoulExecPrivileges({ processImpl });
  return execute(request);
}

export async function runFlySoulBridgeExecCli() {
  try {
    if (process.argv.length !== 3) rejected();
    const encoded = process.argv[2];
    process.argv[2] = "[redacted]";
    const result = executeFlySoulExecTransport(encoded);
    process.stdout.write(`${JSON.stringify(result)}\n`);
    process.exitCode = result.ok ? 0 : 2;
  } catch (error) {
    const code =
      error instanceof FlySoulBridgeError ||
      error instanceof SoulArtifactValidationError
        ? error.code
        : "soul_bridge_failed";
    process.stdout.write(`${JSON.stringify({ ok: false, code })}\n`);
    process.exitCode = 2;
  }
}

if (process.argv[1]?.endsWith("/fly-soul-bridge-exec.mjs")) {
  await runFlySoulBridgeExecCli();
}