@runuai/host 0.9.148 → 0.9.150

package/lib/task-environment/types.ts

@@ -8,6 +8,12 @@
 
 export const TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION = 1 as const;
 
+/** Durable rollout generation for project environment delivery (ADR-153). */
+export type ProjectEnvMode = "baked" | "loader";
+
+/** Every process launch is explicitly classified at the type boundary. */
+export type ProjectEnvProfile = "maintenance" | "task";
+
 export interface TaskEnvironmentLocator {
   schemaVersion: typeof TASK_ENVIRONMENT_LOCATOR_SCHEMA_VERSION;
   /** Stable provider registry key, for example `docker-compose`. */
@@ -19,6 +25,8 @@ export interface TaskEnvironmentLocator {
 export interface TaskEnvironmentDescriptor {
   taskId: string;
   locator: TaskEnvironmentLocator;
+  /** Persisted independently from the provider locator for rollout safety. */
+  envMode?: ProjectEnvMode;
   /** Absolute path as observed inside the environment. */
   workspacePath: string;
   codeServerPort?: number;
@@ -34,9 +42,25 @@ export interface TaskEnvironmentExecRequest {
   /** Host environment names inherited by name, without copying values into argv. */
   inheritEnv?: readonly string[];
   env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
   stdin?: Uint8Array;
   timeoutMs: number;
   maxOutputBytes: number;
+  /**
+   * Run with every capability, as root only: the secrets proxy's NAT step
+   * needs NET_ADMIN, which a task container does not have (ADR-153). Docker
+   * only (`docker exec --privileged`, one process, the container keeps its
+   * default capabilities); every other provider refuses it.
+   */
+  privileged?: true;
+  /**
+   * Called by the provider at the last moment before the process starts,
+   * after anything it awaits first (a machine looks up its address);
+   * throwing refuses the exec unstarted. The secrets proxy's root-step
+   * fence rides on it, so a step's exec cannot start once its operation is
+   * no longer live, however long that lookup takes (ADR-153).
+   */
+  admit?: () => void;
 }
 
 export interface TaskEnvironmentExecResult {
@@ -55,6 +79,7 @@ export interface TaskEnvironmentSpawnRequest {
   /** Host environment names inherited by name, without copying values into argv. */
   inheritEnv?: readonly string[];
   env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
   timeoutMs: number;
   maxOutputBytes: number;
 }
@@ -70,6 +95,7 @@ export interface TaskEnvironmentSessionRequest {
   user?: string;
   inheritEnv?: readonly string[];
   env?: Readonly<Record<string, string>>;
+  projectEnvProfile: ProjectEnvProfile;
   maxOutputBytes: number;
 }
 
@@ -161,6 +187,8 @@ export interface TaskEnvironmentRecoveryContext {
   isCurrent(): boolean;
   /** Drain/tombstone consumers before stopping or repairing a live writer. */
   quarantineConsumers?: () => Promise<void>;
+  /** Reassert task-local security/runtime prerequisites before admission. */
+  prepareConsumers?: () => Promise<void>;
   /** Re-open admission only after the environment is proven operational. */
   allowConsumers?: () => void;
   /** Recreate durable consumers after admission has reopened. */
@@ -232,6 +260,8 @@ export interface TaskEnvironmentHandle<TTeardownResult = void>
 
 export interface TaskEnvironmentProvisionRequest<TInput, TCredentials> {
   taskId: string;
+  /** Omitted only by direct legacy/provider callers; new orchestration passes loader. */
+  envMode?: ProjectEnvMode;
   input: TInput;
   credentials: TCredentials;
   /**
@@ -260,6 +290,7 @@ export interface TaskEnvironmentProvider<
   ): Promise<TaskEnvironmentProvisioned<TResult, TTeardownResult>>;
   reconstruct(
     locator: TaskEnvironmentLocator,
+    envMode?: ProjectEnvMode,
   ): Promise<TaskEnvironmentHandle<TTeardownResult>>;
 }
 
@@ -288,6 +319,17 @@ export function assertWorkspaceScopedPath(
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 /** Shared admission guard for provider implementations and fake providers. */
+/** A one-shot exec: the only request that may be privileged, and then only
+ *  as root. Providers pass the privilege on explicitly, never by reading the
+ *  request, so no other surface can carry it. */
+export function assertTaskEnvironmentExecRequest(request: TaskEnvironmentExecRequest): void {
+  const { privileged, ...unprivileged } = request;
+  if (privileged !== undefined && (privileged !== true || request.user !== "root")) {
+    throw new Error("a privileged task environment exec must run as root");
+  }
+  assertTaskEnvironmentProcessRequest(unprivileged);
+}
+
 export function assertTaskEnvironmentProcessRequest(
   request: TaskEnvironmentExecRequest | TaskEnvironmentSpawnRequest,
 ): void {
@@ -297,6 +339,14 @@ export function assertTaskEnvironmentProcessRequest(
   }
 }
 
+/** For providers with no privileged exec: refuse it rather than run the
+ *  step without the capability it asked for. */
+export function refusePrivilegedExec(request: TaskEnvironmentExecRequest): void {
+  if (request.privileged === true) {
+    throw new Error("this task environment provider has no privileged exec");
+  }
+}
+
 export function assertTaskEnvironmentSessionRequest(
   request:
     | TaskEnvironmentSessionRequest
@@ -304,6 +354,19 @@ export function assertTaskEnvironmentSessionRequest(
     | TaskEnvironmentExecRequest
     | TaskEnvironmentSpawnRequest,
 ): void {
+  // Only a one-shot exec may be privileged (assertTaskEnvironmentExecRequest
+  // strips it after checking); anywhere else it is refused outright.
+  if ("privileged" in request) {
+    throw new Error("only a one-shot task environment exec may be privileged");
+  }
+  if (
+    request.projectEnvProfile !== "maintenance" &&
+    request.projectEnvProfile !== "task"
+  ) {
+    throw new Error(
+      "task environment project env profile must be maintenance or task",
+    );
+  }
   if (
     !Array.isArray(request.argv) ||
     request.argv.length === 0 ||

package/lib/task-gateway-port.ts

@@ -0,0 +1,22 @@
+/**
+ * The port the runner's task gateway listens on (`UAI_MCP_GATEWAY_PORT`,
+ * 5877 by default): where task forwarders relay, and where a machine's
+ * sidecar serves its own task directly on loopback. A module of its own so
+ * the secrets proxy can name it without loading the gateway.
+ */
+
+const DEFAULT_MCP_GATEWAY_PORT = 5877;
+
+function gatewayPort(value: string | undefined): number {
+  if (value === undefined || !/^\d+$/.test(value)) {
+    return DEFAULT_MCP_GATEWAY_PORT;
+  }
+  const port = Number(value);
+  return Number.isSafeInteger(port) && port >= 1 && port <= 65_535
+    ? port
+    : DEFAULT_MCP_GATEWAY_PORT;
+}
+
+export const MCP_GATEWAY_PORT = gatewayPort(
+  process.env.UAI_MCP_GATEWAY_PORT,
+);

package/lib/task-gateway-protocol.ts

@@ -0,0 +1,190 @@
+import {
+  createHmac,
+  timingSafeEqual,
+  type KeyObject,
+} from "node:crypto";
+
+/**
+ * Binary, versioned task-forwarder handshake (ADR-153).
+ *
+ * The leading NUL cannot be the first byte of either HTTP/1.1 or TLS. That
+ * lets the shared gateway reject direct TLS while keeping the existing MCP
+ * HTTP listener on the same port. Length-prefixed fields keep unauthenticated
+ * input bounded before a task identity has been proved.
+ */
+export const TASK_FORWARDER_PREAMBLE_MAGIC = Buffer.from([
+  0x00, 0x55, 0x41, 0x49, 0x46, 0x57, 0x44, 0x01,
+]);
+export const TASK_FORWARDER_CHALLENGE_MAGIC = Buffer.from("UAICHL01", "ascii");
+export const TASK_FORWARDER_RESPONSE_MAGIC = Buffer.from("UAIRES01", "ascii");
+export const TASK_FORWARDER_ACCEPT_MAGIC = Buffer.from("UAIOK001", "ascii");
+
+export const TASK_FORWARDER_SECRET_BYTES = 32;
+/** Numerical container uid reserved for the forwarder (neither root nor node). */
+export const TASK_FORWARDER_UID = 65_532;
+export const TASK_FORWARDER_NONCE_BYTES = 32;
+export const TASK_FORWARDER_MAC_BYTES = 32;
+export const TASK_FORWARDER_MAX_TASK_ID_BYTES = 128;
+export const TASK_FORWARDER_MAX_GENERATION_BYTES = 64;
+export const TASK_FORWARDER_PREAMBLE_HEADER_BYTES =
+  TASK_FORWARDER_PREAMBLE_MAGIC.length + 2;
+export const TASK_FORWARDER_MAX_PREAMBLE_BYTES =
+  TASK_FORWARDER_PREAMBLE_HEADER_BYTES +
+  TASK_FORWARDER_MAX_TASK_ID_BYTES +
+  TASK_FORWARDER_MAX_GENERATION_BYTES;
+export const TASK_FORWARDER_CHALLENGE_BYTES =
+  TASK_FORWARDER_CHALLENGE_MAGIC.length + TASK_FORWARDER_NONCE_BYTES;
+export const TASK_FORWARDER_RESPONSE_BYTES =
+  TASK_FORWARDER_RESPONSE_MAGIC.length + TASK_FORWARDER_MAC_BYTES;
+
+const FORWARDER_HMAC_DOMAIN = Buffer.from(
+  "uai-task-forwarder-v1\0",
+  "ascii",
+);
+const FIELD_SEPARATOR = Buffer.from([0]);
+const FORWARDER_GENERATION = /^[A-Za-z0-9_-]{16,64}$/;
+
+export interface TaskForwarderIdentity {
+  taskId: string;
+  generation: string;
+}
+
+export function encodeTaskForwarderPreamble(
+  identity: TaskForwarderIdentity,
+): Buffer {
+  const taskId = Buffer.from(identity.taskId, "utf8");
+  const generation = Buffer.from(identity.generation, "ascii");
+  if (
+    taskId.length < 1 ||
+    taskId.length > TASK_FORWARDER_MAX_TASK_ID_BYTES ||
+    generation.length < 1 ||
+    generation.length > TASK_FORWARDER_MAX_GENERATION_BYTES ||
+    !FORWARDER_GENERATION.test(identity.generation)
+  ) {
+    throw new Error("invalid task forwarder identity");
+  }
+  return Buffer.concat([
+    TASK_FORWARDER_PREAMBLE_MAGIC,
+    Buffer.from([taskId.length, generation.length]),
+    taskId,
+    generation,
+  ]);
+}
+
+export function taskForwarderPreambleLength(header: Buffer): number | null {
+  if (
+    header.length !== TASK_FORWARDER_PREAMBLE_HEADER_BYTES ||
+    !header.subarray(0, TASK_FORWARDER_PREAMBLE_MAGIC.length).equals(
+      TASK_FORWARDER_PREAMBLE_MAGIC,
+    )
+  ) {
+    return null;
+  }
+  const taskIdBytes = header[TASK_FORWARDER_PREAMBLE_MAGIC.length] ?? 0;
+  const generationBytes =
+    header[TASK_FORWARDER_PREAMBLE_MAGIC.length + 1] ?? 0;
+  if (
+    taskIdBytes < 1 ||
+    taskIdBytes > TASK_FORWARDER_MAX_TASK_ID_BYTES ||
+    generationBytes < 1 ||
+    generationBytes > TASK_FORWARDER_MAX_GENERATION_BYTES
+  ) {
+    return null;
+  }
+  return TASK_FORWARDER_PREAMBLE_HEADER_BYTES + taskIdBytes + generationBytes;
+}
+
+export function decodeTaskForwarderPreamble(
+  preamble: Buffer,
+): TaskForwarderIdentity | null {
+  const header = preamble.subarray(0, TASK_FORWARDER_PREAMBLE_HEADER_BYTES);
+  const expectedLength = taskForwarderPreambleLength(header);
+  if (expectedLength === null || preamble.length !== expectedLength) return null;
+
+  const taskIdBytes = header[TASK_FORWARDER_PREAMBLE_MAGIC.length] ?? 0;
+  const taskStart = TASK_FORWARDER_PREAMBLE_HEADER_BYTES;
+  const generationStart = taskStart + taskIdBytes;
+  const rawTaskId = preamble.subarray(taskStart, generationStart);
+  const rawGeneration = preamble.subarray(generationStart);
+  const taskId = rawTaskId.toString("utf8");
+  const generation = rawGeneration.toString("ascii");
+  // Both Node decoders replace or mask malformed bytes. Require exact
+  // round-trips so two wire identities can never alias the same HMAC input.
+  if (
+    !Buffer.from(taskId, "utf8").equals(rawTaskId) ||
+    !Buffer.from(generation, "ascii").equals(rawGeneration) ||
+    !FORWARDER_GENERATION.test(generation)
+  ) {
+    return null;
+  }
+  return { taskId, generation };
+}
+
+export function encodeTaskForwarderChallenge(nonce: Buffer): Buffer {
+  if (nonce.length !== TASK_FORWARDER_NONCE_BYTES) {
+    throw new Error("invalid task forwarder nonce");
+  }
+  return Buffer.concat([TASK_FORWARDER_CHALLENGE_MAGIC, nonce]);
+}
+
+export function decodeTaskForwarderChallenge(
+  challenge: Buffer,
+): Buffer | null {
+  if (
+    challenge.length !== TASK_FORWARDER_CHALLENGE_BYTES ||
+    !challenge.subarray(0, TASK_FORWARDER_CHALLENGE_MAGIC.length).equals(
+      TASK_FORWARDER_CHALLENGE_MAGIC,
+    )
+  ) {
+    return null;
+  }
+  return Buffer.from(challenge.subarray(TASK_FORWARDER_CHALLENGE_MAGIC.length));
+}
+
+export function taskForwarderMac(
+  secret: Buffer | KeyObject,
+  identity: TaskForwarderIdentity,
+  nonce: Buffer,
+): Buffer {
+  if (nonce.length !== TASK_FORWARDER_NONCE_BYTES) {
+    throw new Error("invalid task forwarder nonce");
+  }
+  return createHmac("sha256", secret)
+    .update(FORWARDER_HMAC_DOMAIN)
+    .update(identity.taskId, "utf8")
+    .update(FIELD_SEPARATOR)
+    .update(identity.generation, "ascii")
+    .update(FIELD_SEPARATOR)
+    .update(nonce)
+    .digest();
+}
+
+export function encodeTaskForwarderResponse(mac: Buffer): Buffer {
+  if (mac.length !== TASK_FORWARDER_MAC_BYTES) {
+    throw new Error("invalid task forwarder response");
+  }
+  return Buffer.concat([TASK_FORWARDER_RESPONSE_MAGIC, mac]);
+}
+
+export function decodeTaskForwarderResponse(response: Buffer): Buffer | null {
+  if (
+    response.length !== TASK_FORWARDER_RESPONSE_BYTES ||
+    !response.subarray(0, TASK_FORWARDER_RESPONSE_MAGIC.length).equals(
+      TASK_FORWARDER_RESPONSE_MAGIC,
+    )
+  ) {
+    return null;
+  }
+  return Buffer.from(response.subarray(TASK_FORWARDER_RESPONSE_MAGIC.length));
+}
+
+export function verifyTaskForwarderMac(
+  expected: Buffer,
+  provided: Buffer,
+): boolean {
+  return (
+    expected.length === TASK_FORWARDER_MAC_BYTES &&
+    provided.length === expected.length &&
+    timingSafeEqual(expected, provided)
+  );
+}

package/lib/task-gateway-recovery.ts

@@ -0,0 +1,44 @@
+import {
+  activeLoaderHostTasks,
+  hostTaskProjectEnvSpec,
+} from "./runtime-state";
+import { taskEnvResolver } from "./task-env-source";
+import { recoverTaskGatewayTask } from "./task-gateway-state";
+
+export interface TaskGatewayRecoverySummary {
+  readonly recovered: number;
+  readonly failed: number;
+}
+
+/**
+ * Reattach value resolvers before the gateway starts listening. Persisted
+ * credentials load inactive, so a malformed row or missing identity stays
+ * fail-closed and its surviving forwarder cannot authenticate.
+ */
+export function recoverActiveTaskGateways(): TaskGatewayRecoverySummary {
+  let recovered = 0;
+  let failed = 0;
+  for (const task of activeLoaderHostTasks()) {
+    try {
+      const spec = hostTaskProjectEnvSpec(task);
+      if (spec === null) {
+        throw new Error("loader task has no persisted project env spec");
+      }
+      const identity = recoverTaskGatewayTask(task.taskId, {
+        resolveEnv: taskEnvResolver(task.taskId, spec),
+      });
+      if (identity === null) {
+        throw new Error("loader task has no valid persisted gateway identity");
+      }
+      recovered += 1;
+    } catch (error) {
+      failed += 1;
+      console.warn(
+        `[task-gateway] task ${task.taskId}: boot recovery stayed closed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  return { recovered, failed };
+}