@runuai/host 0.9.148 → 0.9.150

package/lib/task-gateway-state.ts

@@ -0,0 +1,497 @@
+import {
+  createSecretKey,
+  randomBytes,
+  type KeyObject,
+} from "node:crypto";
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
+import { env } from "./env";
+import {
+  TASK_FORWARDER_SECRET_BYTES,
+  taskForwarderMac,
+  verifyTaskForwarderMac,
+  type TaskForwarderIdentity,
+} from "./task-gateway-protocol";
+import { assertSafeHostTaskId, isSafeHostTaskId } from "./task-identity";
+
+const TASK_GATEWAY_STATE_VERSION = 1 as const;
+const TASK_GATEWAY_MAX_ENV_BYTES = 512 * 1024;
+const TASK_GATEWAY_ETAG = /^"[0-9a-f]{64}"$/;
+
+interface PersistedTaskGatewayIdentity {
+  version: typeof TASK_GATEWAY_STATE_VERSION;
+  taskId: string;
+  generation: string;
+  secret: string;
+}
+
+interface TaskGatewayRecord {
+  readonly taskId: string;
+  readonly generation: string;
+  readonly secret: KeyObject;
+  active: boolean;
+  /** Host lifecycle quarantine; unlike an unproved restart record, this
+   * generation may be restaged and rolled back by the same process. */
+  suspended: boolean;
+  resolveEnv: TaskGatewayEnvResolver | null;
+  snapshot: TaskGatewayEnvSnapshot | null;
+}
+
+export interface TaskGatewayRegistration extends TaskForwarderIdentity {}
+
+/**
+ * A complete, already-rendered loader response. The renderer owns the POSIX
+ * quoting and managed-key list. The gateway verifies its final sentinel and
+ * exact quoted lowercase-SHA-256 ETag, then sends these bytes unchanged.
+ */
+export interface TaskGatewayEnvSnapshot {
+  readonly body: string | Uint8Array;
+  readonly etag: string;
+}
+
+export type TaskGatewayEnvResolver = () =>
+  | TaskGatewayEnvSnapshot
+  | null;
+
+export interface ResolvedTaskGatewayEnv {
+  readonly body: Buffer;
+  readonly etag: string;
+}
+
+export interface RegisterTaskGatewayOptions {
+  resolveEnv?: TaskGatewayEnvResolver;
+  snapshot?: TaskGatewayEnvSnapshot;
+}
+
+type RevocationListener = (identity: TaskGatewayRegistration) => void;
+
+const records = new Map<string, TaskGatewayRecord>();
+const revocationListeners = new Set<RevocationListener>();
+
+function stateDir(): string {
+  return resolve(env.dataDir, "task-gateway");
+}
+
+function statePath(taskId: string): string {
+  return resolve(stateDir(), `${taskId}.json`);
+}
+
+function stateDirectoryIsPrivate(): boolean {
+  try {
+    const metadata = lstatSync(stateDir());
+    return (
+      metadata.isDirectory() &&
+      !metadata.isSymbolicLink() &&
+      (metadata.mode & 0o077) === 0 &&
+      (process.getuid === undefined || metadata.uid === process.getuid())
+    );
+  } catch {
+    return false;
+  }
+}
+
+function parseSecret(value: unknown): Buffer | null {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    return null;
+  }
+  const decoded = Buffer.from(value, "base64url");
+  return decoded.length === TASK_FORWARDER_SECRET_BYTES &&
+    decoded.toString("base64url") === value
+    ? decoded
+    : null;
+}
+
+function persistedRecord(taskId: string): TaskGatewayRecord | null {
+  assertSafeHostTaskId(taskId);
+  if (!stateDirectoryIsPrivate()) return null;
+  try {
+    const path = statePath(taskId);
+    const metadata = lstatSync(path);
+    // A task-controlled symlink must never redirect a credential read. Host
+    // state is private already; requiring no group/other bits makes that
+    // boundary explicit and catches an accidentally broad installation.
+    if (
+      !metadata.isFile() ||
+      metadata.isSymbolicLink() ||
+      (metadata.mode & 0o077) !== 0 ||
+      (process.getuid !== undefined && metadata.uid !== process.getuid())
+    ) {
+      return null;
+    }
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<
+      PersistedTaskGatewayIdentity
+    >;
+    const secret = parseSecret(parsed.secret);
+    if (
+      parsed.version !== TASK_GATEWAY_STATE_VERSION ||
+      parsed.taskId !== taskId ||
+      typeof parsed.generation !== "string" ||
+      !/^[A-Za-z0-9_-]{16,64}$/.test(parsed.generation) ||
+      secret === null
+    ) {
+      secret?.fill(0);
+      return null;
+    }
+    const key = createSecretKey(secret);
+    secret.fill(0);
+    return {
+      taskId,
+      generation: parsed.generation,
+      secret: key,
+      // Durable state proves a surviving forwarder's secret, but not that the
+      // task still exists. Lifecycle recovery must explicitly reactivate it.
+      active: false,
+      suspended: false,
+      resolveEnv: null,
+      snapshot: null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function currentRecord(taskId: string): TaskGatewayRecord | null {
+  const cached = records.get(taskId);
+  if (cached) return cached;
+  if (!isSafeHostTaskId(taskId)) return null;
+  const loaded = persistedRecord(taskId);
+  if (loaded) records.set(taskId, loaded);
+  return loaded;
+}
+
+function persistIdentity(
+  identity: TaskGatewayRegistration,
+  secret: Buffer,
+): void {
+  mkdirSync(stateDir(), { recursive: true, mode: 0o700 });
+  if (!stateDirectoryIsPrivate()) {
+    // Tighten an older host-created directory, but never follow a symlink or
+    // adopt a directory owned by another account.
+    const metadata = lstatSync(stateDir());
+    if (
+      !metadata.isDirectory() ||
+      metadata.isSymbolicLink() ||
+      (process.getuid !== undefined && metadata.uid !== process.getuid())
+    ) {
+      throw new Error("unsafe task gateway state directory");
+    }
+    chmodSync(stateDir(), 0o700);
+  }
+  const path = statePath(identity.taskId);
+  const temporary = resolve(
+    stateDir(),
+    `.${identity.taskId}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`,
+  );
+  const serialized = JSON.stringify({
+    version: TASK_GATEWAY_STATE_VERSION,
+    taskId: identity.taskId,
+    generation: identity.generation,
+    secret: secret.toString("base64url"),
+  } satisfies PersistedTaskGatewayIdentity);
+  try {
+    writeFileSync(temporary, serialized, { flag: "wx", mode: 0o600 });
+    renameSync(temporary, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function notifyRevoked(record: TaskGatewayRecord): void {
+  const identity = {
+    taskId: record.taskId,
+    generation: record.generation,
+  };
+  for (const listener of revocationListeners) {
+    try {
+      listener(identity);
+    } catch {
+      // Revocation must continue even if one socket owner misbehaves.
+    }
+  }
+}
+
+function assignEnv(
+  record: TaskGatewayRecord,
+  options: RegisterTaskGatewayOptions,
+): void {
+  if (options.resolveEnv && options.snapshot) {
+    throw new Error("task gateway env must use a resolver or snapshot, not both");
+  }
+  record.resolveEnv = options.resolveEnv ?? null;
+  record.snapshot = options.snapshot ?? null;
+}
+
+/** Mint and durably register a fresh task generation. */
+export function registerTaskGatewayTask(
+  taskId: string,
+  options: RegisterTaskGatewayOptions = {},
+): TaskGatewayRegistration {
+  assertSafeHostTaskId(taskId);
+  if (options.resolveEnv && options.snapshot) {
+    throw new Error("task gateway env must use a resolver or snapshot, not both");
+  }
+  const previous = currentRecord(taskId);
+  const secret = randomBytes(TASK_FORWARDER_SECRET_BYTES);
+  const identity = {
+    taskId,
+    generation: randomBytes(18).toString("base64url"),
+  };
+  try {
+    persistIdentity(identity, secret);
+    const record: TaskGatewayRecord = {
+      ...identity,
+      secret: createSecretKey(secret),
+      active: true,
+      suspended: false,
+      resolveEnv: null,
+      snapshot: null,
+    };
+    assignEnv(record, options);
+    records.set(taskId, record);
+    if (previous) notifyRevoked(previous);
+    return identity;
+  } finally {
+    secret.fill(0);
+  }
+}
+
+/**
+ * Reattach in-memory env state to a generation that survived a host restart.
+ * Corrupt or absent state returns null; callers then rotate and restart the
+ * task forwarder instead of accepting an unproved identity.
+ */
+export function recoverTaskGatewayTask(
+  taskId: string,
+  options: RegisterTaskGatewayOptions = {},
+): TaskGatewayRegistration | null {
+  assertSafeHostTaskId(taskId);
+  const record = currentRecord(taskId);
+  if (!record) return null;
+  assignEnv(record, options);
+  record.active = true;
+  record.suspended = false;
+  return { taskId, generation: record.generation };
+}
+
+/**
+ * A fresh fixed-size copy intended only for the forwarder's stdin. Host
+ * recovery may stage a replacement forwarder while the generation is
+ * suspended; authentication remains closed until reactivateTaskGatewayTask.
+ */
+export function taskGatewayForwarderSecretInput(
+  taskId: string,
+  generation: string,
+): Uint8Array | null {
+  const record = currentRecord(taskId);
+  if (
+    !record ||
+    (!record.active && !record.suspended) ||
+    record.generation !== generation
+  ) {
+    return null;
+  }
+  const exported = record.secret.export();
+  const bytes = Buffer.isBuffer(exported) ? exported : Buffer.from(exported);
+  if (bytes.length !== TASK_FORWARDER_SECRET_BYTES) {
+    bytes.fill(0);
+    return null;
+  }
+  const copy = Uint8Array.from(bytes);
+  bytes.fill(0);
+  return copy;
+}
+
+export function setTaskGatewayEnvResolver(
+  taskId: string,
+  generation: string,
+  resolveEnv: TaskGatewayEnvResolver,
+): boolean {
+  const record = currentRecord(taskId);
+  if (!record || !record.active || record.generation !== generation) return false;
+  record.resolveEnv = resolveEnv;
+  record.snapshot = null;
+  return true;
+}
+
+/** Snapshot convenience for runtimes whose env source already fans out updates. */
+export function updateTaskGatewayEnv(
+  taskId: string,
+  generation: string,
+  snapshot: TaskGatewayEnvSnapshot,
+): boolean {
+  const record = currentRecord(taskId);
+  if (!record || !record.active || record.generation !== generation) return false;
+  record.snapshot = snapshot;
+  record.resolveEnv = null;
+  return true;
+}
+
+function normalizeEnvSnapshot(
+  snapshot: TaskGatewayEnvSnapshot | null,
+): ResolvedTaskGatewayEnv | null {
+  if (snapshot === null || !TASK_GATEWAY_ETAG.test(snapshot.etag)) return null;
+  const body =
+    typeof snapshot.body === "string"
+      ? Buffer.from(snapshot.body, "utf8")
+      : Buffer.from(snapshot.body);
+  if (
+    body.length > TASK_GATEWAY_MAX_ENV_BYTES ||
+    body.includes(0)
+  ) {
+    return null;
+  }
+  const text = body.toString("utf8");
+  const rawEtag = snapshot.etag.slice(1, -1);
+  if (
+    !Buffer.from(text, "utf8").equals(body) ||
+    !text.endsWith(`# uai-env-v1 end=${rawEtag}\n`)
+  ) {
+    return null;
+  }
+  return { body, etag: snapshot.etag };
+}
+
+/** Resolve on every request so rotations/deletions are visible immediately. */
+export function resolveTaskGatewayEnv(
+  identity: TaskGatewayRegistration,
+): ResolvedTaskGatewayEnv | null {
+  const record = currentRecord(identity.taskId);
+  if (
+    !record ||
+    !record.active ||
+    record.generation !== identity.generation
+  ) {
+    return null;
+  }
+  let snapshot: TaskGatewayEnvSnapshot | null;
+  try {
+    snapshot = record.resolveEnv ? record.resolveEnv() : record.snapshot;
+  } catch {
+    return null;
+  }
+  return normalizeEnvSnapshot(snapshot);
+}
+
+export function isTaskGatewayGenerationCurrent(
+  identity: TaskGatewayRegistration,
+): boolean {
+  const record = currentRecord(identity.taskId);
+  return record?.active === true && record.generation === identity.generation;
+}
+
+/** Current non-secret identity, used by the fixed-task sidecar listener. */
+export function currentTaskGatewayRegistration(
+  taskId: string,
+): TaskGatewayRegistration | null {
+  const record = currentRecord(taskId);
+  return record?.active
+    ? { taskId: record.taskId, generation: record.generation }
+    : null;
+}
+
+/** Trusted recovery identity, available while public authentication is shut. */
+export function taskGatewayRegistrationForRecovery(
+  taskId: string,
+): TaskGatewayRegistration | null {
+  const record = currentRecord(taskId);
+  return record && (record.active || record.suspended)
+    ? { taskId: record.taskId, generation: record.generation }
+    : null;
+}
+
+/**
+ * Immediately close a live generation while retaining its durable identity.
+ * Runtime pause/recovery uses this before the first stop; a failed stop can
+ * reactivate the same generation without ever minting a second authority.
+ */
+export function suspendTaskGatewayTask(
+  taskId: string,
+): TaskGatewayRegistration | null {
+  const record = currentRecord(taskId);
+  if (!record || !record.active) return null;
+  record.active = false;
+  record.suspended = true;
+  notifyRevoked(record);
+  return { taskId: record.taskId, generation: record.generation };
+}
+
+/** Same-process rollback for a failed pause/maintenance stop. */
+export function reactivateTaskGatewayTask(
+  identity: TaskGatewayRegistration,
+): boolean {
+  const record = currentRecord(identity.taskId);
+  if (
+    !record ||
+    !record.suspended ||
+    record.generation !== identity.generation
+  ) {
+    return false;
+  }
+  record.active = true;
+  record.suspended = false;
+  return true;
+}
+
+export function verifyTaskGatewayAuthentication(
+  identity: TaskGatewayRegistration,
+  nonce: Buffer,
+  providedMac: Buffer,
+): boolean {
+  const record = currentRecord(identity.taskId);
+  if (
+    !record ||
+    !record.active ||
+    record.generation !== identity.generation
+  ) {
+    return false;
+  }
+  try {
+    return verifyTaskForwarderMac(
+      taskForwarderMac(record.secret, identity, nonce),
+      providedMac,
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Generation-fenced teardown: a stale stop cannot revoke a replacement. */
+export function removeTaskGatewayTask(
+  taskId: string,
+  generation?: string,
+): boolean {
+  if (!isSafeHostTaskId(taskId)) return false;
+  const record = currentRecord(taskId);
+  if (!record || (generation !== undefined && record.generation !== generation)) {
+    return false;
+  }
+  // Revoke live authority first. If durable cleanup fails, this process stays
+  // closed and a restarted process loads the leftover generation inactive
+  // until explicit task recovery; surface the deletion error to the caller.
+  records.delete(taskId);
+  notifyRevoked(record);
+  rmSync(statePath(taskId), { force: true });
+  return true;
+}
+
+export function subscribeTaskGatewayRevocations(
+  listener: RevocationListener,
+): () => void {
+  revocationListeners.add(listener);
+  return () => revocationListeners.delete(listener);
+}
+
+/** Test-only cache reset; temp data directories remain owned by each test. */
+export function resetTaskGatewayStateForTests(): void {
+  records.clear();
+  revocationListeners.clear();
+}

package/lib/transcript.ts

@@ -66,6 +66,7 @@ async function appendOneViaEnvironment(
 ): Promise<void> {
   const path = `${environment.descriptor.workspacePath}/.uai/${TARGET_FILENAME[target]}`;
   const proc = await environment.spawn({
+    projectEnvProfile: "maintenance",
     argv: [
       "/bin/sh",
       "-c",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.148",
+  "version": "0.9.150",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",
@@ -56,6 +56,18 @@
     "./protocol": {
       "types": "./src/protocol.ts",
       "default": "./src/protocol.ts"
+    },
+    "./project-env-policy": {
+      "types": "./src/project-env-policy.ts",
+      "default": "./src/project-env-policy.ts"
+    },
+    "./project-env-latest": {
+      "types": "./src/project-env-latest.ts",
+      "default": "./src/project-env-latest.ts"
+    },
+    "./project-env-wording": {
+      "types": "./src/project-env-wording.ts",
+      "default": "./src/project-env-wording.ts"
     }
   },
   "scripts": {