@runuai/host 0.9.81 → 0.9.83

package/lib/machine-provider-aws.ts

@@ -33,6 +33,17 @@ import type {
 
 export const AWS_MACHINE_TAG = "com.uai.machine";
 
+/** ADR-125 BYO-AWS: the Uai account that publishes the public payload AMIs,
+ * and the name prefix build-ami.sh stamps on them. A host with no
+ * UAI_MACHINE_IMAGE resolves the newest published payload in its region. */
+export const PAYLOAD_AMI_OWNER = "277057415208";
+export const PAYLOAD_AMI_NAME_PREFIX = "uai-machine-payload";
+/** Name of the security group auto-created in the default VPC when the host
+ * config names none. Inbound: all TCP from the HOST's egress /32 only —
+ * code-server runs auth-none and preview ports are plain HTTP, so exposure
+ * wider than the orchestrator would hand the editor to the internet. */
+const MANAGED_SECURITY_GROUP = "uai-machines";
+
 export interface AwsMachineConfig {
   region: string;
   /** AMI id used when the spec's image is not already an ami-*. */
@@ -219,6 +230,30 @@ function unknown(id: string, detail: string): MachineInfo {
   return { id, taskLabel: null, state: "unknown", address: null, detail };
 }
 
+/** The host's public egress address, for scoping the auto-created security
+ * group. Only consulted when the group must be CREATED — an existing group
+ * (explicit config or a prior run) never re-resolves. Overridable for hosts
+ * whose egress the checker cannot see (e.g. VPN'd). */
+async function hostEgressIp(): Promise<string> {
+  const configured = process.env.UAI_HOST_EGRESS_IP;
+  if (configured && /^\d{1,3}(\.\d{1,3}){3}$/.test(configured)) {
+    return configured;
+  }
+  try {
+    const res = await fetch("https://checkip.amazonaws.com", {
+      signal: AbortSignal.timeout(5_000),
+    });
+    const ip = (await res.text()).trim();
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) return ip;
+  } catch {
+    // fall through to the instruction below
+  }
+  throw new Error(
+    "could not determine this host's public address to scope the machine " +
+      "security group — set UAI_HOST_EGRESS_IP or UAI_AWS_SECURITY_GROUP_ID",
+  );
+}
+
 export function createAwsMachineProvider(
   config: AwsMachineConfig,
   runner: Runner = defaultRunner(config.region),
@@ -265,6 +300,171 @@ export function createAwsMachineProvider(
     return device;
   }
 
+  // -------------------------------------------------------------------------
+  // ADR-125 BYO-AWS zero-config discovery. Every resolver prefers explicit
+  // host config, resolves once per process, and fails with an instruction
+  // rather than a guess — a wrong subnet or security group is a machine the
+  // orchestrator can never reach.
+  // -------------------------------------------------------------------------
+
+  let resolvedImage: string | null = null;
+  async function resolveImage(specImage: string): Promise<string> {
+    if (specImage.startsWith("ami-")) return specImage;
+    if (resolvedImage) return resolvedImage;
+    const res = await runner([
+      "ec2",
+      "describe-images",
+      "--owners",
+      PAYLOAD_AMI_OWNER,
+      "--filters",
+      `Name=name,Values=${PAYLOAD_AMI_NAME_PREFIX}-*`,
+      "Name=state,Values=available",
+      "--query",
+      "sort_by(Images, &CreationDate)[-1].ImageId",
+    ]);
+    let image: unknown = null;
+    if (res.status === 0) {
+      try {
+        image = JSON.parse(res.stdout);
+      } catch {
+        image = null;
+      }
+    }
+    if (typeof image !== "string" || !image.startsWith("ami-")) {
+      throw new Error(
+        `no uai machine payload AMI is published in ${config.region} — set ` +
+          "UAI_MACHINE_IMAGE to an AMI id, or ask Uai to publish this region",
+      );
+    }
+    resolvedImage = image;
+    return image;
+  }
+
+  let resolvedSubnet: string | null = null;
+  async function resolveSubnet(): Promise<string> {
+    if (config.subnetId) return config.subnetId;
+    if (resolvedSubnet) return resolvedSubnet;
+    const res = await runner([
+      "ec2",
+      "describe-subnets",
+      "--filters",
+      "Name=default-for-az,Values=true",
+      "--query",
+      "sort_by(Subnets, &AvailabilityZone)[].{id: SubnetId, public: MapPublicIpOnLaunch, vpc: VpcId}",
+    ]);
+    let subnets: Array<{ id?: unknown; public?: unknown }> = [];
+    if (res.status === 0) {
+      try {
+        const parsed = JSON.parse(res.stdout);
+        if (Array.isArray(parsed)) subnets = parsed;
+      } catch {
+        subnets = [];
+      }
+    }
+    const chosen =
+      subnets.find((s) => s.public === true && typeof s.id === "string") ??
+      subnets.find((s) => typeof s.id === "string");
+    if (!chosen || typeof chosen.id !== "string") {
+      throw new Error(
+        `no default-VPC subnet found in ${config.region} — set ` +
+          "UAI_AWS_SUBNET_ID to a public subnet",
+      );
+    }
+    resolvedSubnet = chosen.id;
+    return chosen.id;
+  }
+
+  let resolvedSecurityGroup: string | null = null;
+  async function resolveSecurityGroup(subnetId: string): Promise<string> {
+    if (config.securityGroupId) return config.securityGroupId;
+    if (resolvedSecurityGroup) return resolvedSecurityGroup;
+    const vpcRes = await runner([
+      "ec2",
+      "describe-subnets",
+      "--subnet-ids",
+      subnetId,
+      "--query",
+      "Subnets[0].VpcId",
+    ]);
+    const vpcId = vpcRes.status === 0 ? JSON.parse(vpcRes.stdout) : null;
+    if (typeof vpcId !== "string") {
+      throw new Error(`could not resolve the VPC of subnet ${subnetId}`);
+    }
+    const found = await runner([
+      "ec2",
+      "describe-security-groups",
+      "--filters",
+      `Name=group-name,Values=${MANAGED_SECURITY_GROUP}`,
+      `Name=vpc-id,Values=${vpcId}`,
+      "--query",
+      "SecurityGroups[0].GroupId",
+    ]);
+    if (found.status === 0) {
+      try {
+        const existing = JSON.parse(found.stdout);
+        if (typeof existing === "string" && existing.startsWith("sg-")) {
+          resolvedSecurityGroup = existing;
+          return existing;
+        }
+      } catch {
+        // fall through to creation
+      }
+    }
+    const egress = await hostEgressIp();
+    const created = await runner([
+      "ec2",
+      "create-security-group",
+      "--group-name",
+      MANAGED_SECURITY_GROUP,
+      "--description",
+      "uai task machines: reachable only from the orchestrating host",
+      "--vpc-id",
+      vpcId,
+      "--query",
+      "GroupId",
+    ]);
+    const groupId = created.status === 0 ? JSON.parse(created.stdout) : null;
+    if (typeof groupId !== "string") {
+      throw new Error(
+        `could not create the ${MANAGED_SECURITY_GROUP} security group: ${
+          created.stderr.trim() || `exit ${created.status ?? "killed"}`
+        }`,
+      );
+    }
+    const authorized = await runner([
+      "ec2",
+      "authorize-security-group-ingress",
+      "--group-id",
+      groupId,
+      "--ip-permissions",
+      JSON.stringify([
+        {
+          IpProtocol: "tcp",
+          FromPort: 0,
+          ToPort: 65535,
+          IpRanges: [
+            {
+              CidrIp: `${egress}/32`,
+              Description: "uai orchestrating host",
+            },
+          ],
+        },
+      ]),
+    ]);
+    if (authorized.status !== 0) {
+      throw new Error(
+        `created ${groupId} but could not authorize the host's address: ${
+          authorized.stderr.trim() || `exit ${authorized.status ?? "killed"}`
+        }`,
+      );
+    }
+    console.log(
+      `[machine-aws] created security group ${groupId} (${MANAGED_SECURITY_GROUP}) allowing ${egress}/32`,
+    );
+    resolvedSecurityGroup = groupId;
+    return groupId;
+  }
+
   /** Resolve the logical machine id to its live instances via the tag. */
   async function resolveLive(
     machineId: string,
@@ -338,16 +538,21 @@ export function createAwsMachineProvider(
       // name the AMI's actual root device — a wrong name would ADD a blank
       // volume while the root stays small — so resolve it per image.
       const diskGiB = config.diskGiB ?? DEFAULT_DISK_GIB;
-      const rootDevice = await rootDeviceName(spec.image);
+      // ADR-125 BYO-AWS: explicit config wins; otherwise resolve the newest
+      // published payload AMI and the default-VPC network per process.
+      const image = await resolveImage(spec.image);
+      const subnetId = await resolveSubnet();
+      const securityGroupId = await resolveSecurityGroup(subnetId);
+      const rootDevice = await rootDeviceName(image);
       // a live machine.
       const launchFingerprint = createHash("sha256")
         .update(
           JSON.stringify([
-            spec.image,
+            image,
             type,
             spec.authorizedPublicKey ?? null,
-            config.subnetId ?? null,
-            config.securityGroupId ?? null,
+            subnetId,
+            securityGroupId,
             config.iamInstanceProfileArn ?? null,
             diskGiB,
           ]),
@@ -358,7 +563,7 @@ export function createAwsMachineProvider(
         "ec2",
         "run-instances",
         "--image-id",
-        spec.image,
+        image,
         "--instance-type",
         type,
         "--count",
@@ -383,10 +588,10 @@ export function createAwsMachineProvider(
         ...(spec.authorizedPublicKey
           ? ["--user-data", awsUserData(spec.authorizedPublicKey)]
           : []),
-        ...(config.subnetId ? ["--subnet-id", config.subnetId] : []),
-        ...(config.securityGroupId
-          ? ["--security-group-ids", config.securityGroupId]
-          : []),
+        "--subnet-id",
+        subnetId,
+        "--security-group-ids",
+        securityGroupId,
         ...(config.iamInstanceProfileArn
           ? ["--iam-instance-profile", `Arn=${config.iamInstanceProfileArn}`]
           : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.81",
+  "version": "0.9.83",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/cli.ts

@@ -20,7 +20,11 @@
 // runs far too late.)
 import "./load-env";
 
-import { spawn, spawnSync } from "node:child_process";
+import {
+  spawn,
+  spawnSync,
+  type SpawnSyncReturns,
+} from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
@@ -139,6 +143,11 @@ async function main(): Promise<void> {
       return cmdRuntime(rest);
     case "tune":
       return cmdTune();
+    case "aws":
+      if (rest[0] === "setup") return cmdAwsSetup(rest.slice(1));
+      console.error(red("usage: uai-host aws setup [--region <region>] [--rotate]"));
+      process.exitCode = 1;
+      return;
     case "update":
       return cmdUpdate(rest);
     case "rollback":
@@ -500,6 +509,234 @@ async function boundedResponseJson(
 
 // --- runtime ---------------------------------------------------------------
 
+// --- aws setup (ADR-125 BYO-AWS: mint the host's scoped AWS identity) --------
+
+/** Mirrors scripts/machine-ami/byo-aws-quickcreate.yaml — keep in sync. */
+const AWS_MACHINE_POLICY = {
+  Version: "2012-10-17",
+  Statement: [
+    {
+      Sid: "UaiMachines",
+      Effect: "Allow",
+      Action: [
+        "ec2:RunInstances",
+        "ec2:StartInstances",
+        "ec2:StopInstances",
+        "ec2:TerminateInstances",
+        "ec2:CreateTags",
+        "ec2:DescribeInstances",
+        "ec2:DescribeImages",
+        "ec2:DescribeSubnets",
+        "ec2:DescribeVpcs",
+        "ec2:DescribeSecurityGroups",
+        "ec2:CreateSecurityGroup",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:CreateSnapshot",
+        "ec2:DeleteSnapshot",
+        "ec2:CreateVolume",
+        "ec2:DescribeSnapshots",
+        "ec2:DescribeVolumes",
+      ],
+      Resource: "*",
+    },
+  ],
+};
+const AWS_SETUP_USER = "uai-host";
+
+/** Run the aws CLI with the operator's AMBIENT (admin) credentials: any
+ * AWS_* that load-env pulled from .env.local is a previously-minted SCOPED
+ * key that cannot administer IAM, and letting it shadow the shell's admin
+ * credentials makes every failure read as a permissions mystery. */
+function awsAdmin(
+  args: string[],
+  region: string | null,
+): SpawnSyncReturns<string> {
+  const env = { ...process.env };
+  const fromFile = (() => {
+    try {
+      return parseDotenv(readFileSync(envLocalPath(), "utf8"));
+    } catch {
+      return {} as Record<string, string>;
+    }
+  })();
+  if (
+    env.AWS_ACCESS_KEY_ID &&
+    env.AWS_ACCESS_KEY_ID === fromFile.AWS_ACCESS_KEY_ID
+  ) {
+    delete env.AWS_ACCESS_KEY_ID;
+    delete env.AWS_SECRET_ACCESS_KEY;
+    delete env.AWS_SESSION_TOKEN;
+  }
+  return spawnSync(
+    "aws",
+    [...(region ? ["--region", region] : []), "--output", "json", ...args],
+    { encoding: "utf8", env },
+  );
+}
+
+async function cmdAwsSetup(rest: string[]): Promise<void> {
+  const rotate = rest.includes("--rotate");
+  const regionFlagAt = rest.indexOf("--region");
+  let region = regionFlagAt >= 0 ? (rest[regionFlagAt + 1] ?? "") : "";
+
+  const version = spawnSync("aws", ["--version"], { encoding: "utf8" });
+  if (version.status !== 0) {
+    console.error(red("the aws CLI is not installed (or not on PATH)"));
+    console.error("install it: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html");
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!region) {
+    const configured = spawnSync("aws", ["configure", "get", "region"], {
+      encoding: "utf8",
+    });
+    region = (configured.stdout ?? "").trim();
+  }
+  if (!region) {
+    console.error(red("no AWS region — pass --region <region> (e.g. --region us-west-2)"));
+    process.exitCode = 1;
+    return;
+  }
+
+  const identity = awsAdmin(["sts", "get-caller-identity"], region);
+  if (identity.status !== 0) {
+    console.error(red("no working AWS admin credentials in this shell"));
+    console.error(
+      "sign in first (aws configure, aws sso login, or exported AWS_* vars), then re-run",
+    );
+    console.error(dim((identity.stderr ?? "").trim().slice(0, 200)));
+    process.exitCode = 1;
+    return;
+  }
+  const account = (() => {
+    try {
+      return (JSON.parse(identity.stdout) as { Account?: string }).Account ?? "?";
+    } catch {
+      return "?";
+    }
+  })();
+
+  const existingEnv = (() => {
+    try {
+      return parseDotenv(readFileSync(envLocalPath(), "utf8"));
+    } catch {
+      return {} as Record<string, string>;
+    }
+  })();
+  if (existingEnv.AWS_ACCESS_KEY_ID && !rotate) {
+    console.log(
+      `already configured (key ${existingEnv.AWS_ACCESS_KEY_ID.slice(0, 8)}…, region ${existingEnv.UAI_AWS_REGION ?? "?"})`,
+    );
+    console.log(`re-run with ${bold("--rotate")} to mint a fresh key`);
+    return;
+  }
+
+  console.log(`account ${account}, region ${region} — creating the ${AWS_SETUP_USER} identity`);
+
+  const created = awsAdmin(
+    ["iam", "create-user", "--user-name", AWS_SETUP_USER],
+    region,
+  );
+  if (
+    created.status !== 0 &&
+    !(created.stderr ?? "").includes("EntityAlreadyExists")
+  ) {
+    console.error(red(`could not create the ${AWS_SETUP_USER} IAM user: ${(created.stderr ?? "").trim().slice(0, 300)}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // put-user-policy overwrites: re-running upgrades the policy in place.
+  const policy = awsAdmin(
+    [
+      "iam",
+      "put-user-policy",
+      "--user-name",
+      AWS_SETUP_USER,
+      "--policy-name",
+      "uai-machines",
+      "--policy-document",
+      JSON.stringify(AWS_MACHINE_POLICY),
+    ],
+    region,
+  );
+  if (policy.status !== 0) {
+    console.error(red(`could not attach the machine policy: ${(policy.stderr ?? "").trim().slice(0, 300)}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const keyResult = awsAdmin(
+    ["iam", "create-access-key", "--user-name", AWS_SETUP_USER],
+    region,
+  );
+  if (keyResult.status !== 0) {
+    console.error(red(`could not create an access key: ${(keyResult.stderr ?? "").trim().slice(0, 300)}`));
+    if ((keyResult.stderr ?? "").includes("LimitExceeded")) {
+      console.error(
+        `the user already has two keys — list them with: aws iam list-access-keys --user-name ${AWS_SETUP_USER}\n` +
+          `and delete one with: aws iam delete-access-key --user-name ${AWS_SETUP_USER} --access-key-id <id>`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+  let keyId = "";
+  let secret = "";
+  try {
+    const parsed = JSON.parse(keyResult.stdout) as {
+      AccessKey?: { AccessKeyId?: string; SecretAccessKey?: string };
+    };
+    keyId = parsed.AccessKey?.AccessKeyId ?? "";
+    secret = parsed.AccessKey?.SecretAccessKey ?? "";
+  } catch {
+    // handled below
+  }
+  if (!keyId || !secret) {
+    console.error(red("create-access-key returned no key material"));
+    process.exitCode = 1;
+    return;
+  }
+
+  writeEnvValuesAtomic(envLocalPath(), {
+    UAI_MACHINE_TASKS: "1",
+    UAI_MACHINE_PROVIDER: "aws",
+    UAI_AWS_REGION: region,
+    AWS_ACCESS_KEY_ID: keyId,
+    AWS_SECRET_ACCESS_KEY: secret,
+  });
+
+  // Rotation hygiene: the key the env file carried before this run belongs
+  // to the scoped user; a minted replacement leaves it orphaned AND holding
+  // the 2-key limit. Best-effort delete, loudly skippable.
+  const previousKey = existingEnv.AWS_ACCESS_KEY_ID;
+  if (rotate && previousKey && previousKey !== keyId) {
+    const deleted = awsAdmin(
+      [
+        "iam",
+        "delete-access-key",
+        "--user-name",
+        AWS_SETUP_USER,
+        "--access-key-id",
+        previousKey,
+      ],
+      region,
+    );
+    if (deleted.status === 0) {
+      console.log(`rotated: deleted the previous key ${previousKey.slice(0, 8)}…`);
+    } else {
+      console.log(
+        yellow(`minted a new key but could not delete ${previousKey.slice(0, 8)}… — remove it manually if unused`),
+      );
+    }
+  }
+
+  console.log(`${bold("done")} — scoped credentials written to ${envLocalPath()}`);
+  console.log(`  UAI_MACHINE_PROVIDER=aws  UAI_AWS_REGION=${region}  (machine tasks enabled)`);
+  console.log(`restart the host to activate: ${cyan("uai-host restart")}`);
+}
+
 // --- tune (ADR-118 follow-up: vnode/file-table ceilings) ---------------------
 
 const TUNE_DAEMON_LABEL = "com.runuai.tune";
@@ -2019,6 +2256,10 @@ function printHelp(): void {
   runtime recheck      probe Docker again and refresh cloud capabilities
   tune                 (macOS, sudo) raise kernel vnode/file-table ceilings for
                        apple-container task VMs and persist them across boots
+  aws setup [--region <r>] [--rotate]
+                       enable machine-backed tasks in YOUR AWS account: uses
+                       the admin credentials already in this shell to mint a
+                       scoped uai-host IAM key and writes the host config
   setup --cloud <wss-url> --enroll <token>
                        claim this machine via an enrollment token from the web
                        app (mints + writes the host credential); on an