@runuai/host 0.9.147 → 0.9.149

package/lib/project-env-feature.ts

@@ -0,0 +1,74 @@
+/**
+ * Host-only release switch for ADR-153 project-env bindings.
+ *
+ * Capability advertisement and task admission move together: once a sidecar
+ * advertises the protocol, its task cannot expose a legacy env view before the
+ * replica's first complete reconciliation. Advertisement also waits for the
+ * durable managed-runtime floor, so no acknowledged generation can roll back
+ * to code that serves the old value-only store.
+ */
+import { PROJECT_ENV_BINDINGS_PROTOCOL_FEATURE } from "../src/protocol";
+import { PROJECT_ENV_POLICY_EPOCHS } from "../src/project-env-policy";
+import { MANAGED_RUNTIME_CAPABILITY_VERSION } from "./runtime-archive";
+
+const PROJECT_ENV_BINDINGS_ENABLED = true;
+export const PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY =
+  MANAGED_RUNTIME_CAPABILITY_VERSION;
+
+let capabilityFloorClaim: Promise<void> | null = null;
+let capabilityFloorClaimFailed = false;
+let capabilityReady = false;
+
+/**
+ * Claim the irreversible rollback floor before the first capability frame.
+ * The rejected promise is deliberately retained: one process gets one claim
+ * attempt and stays fail-closed until restart if durable persistence fails.
+ */
+export async function initializeProjectEnvBindingCapability(
+  claimFloor: (minimumCapability: number) => Promise<void>,
+): Promise<boolean> {
+  if (!PROJECT_ENV_BINDINGS_ENABLED) return false;
+  capabilityFloorClaim ??= Promise.resolve()
+    .then(() => claimFloor(PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY))
+    .then(() => {
+      capabilityReady = true;
+    })
+    .catch((error: unknown) => {
+      capabilityFloorClaimFailed = true;
+      throw error;
+    });
+  await capabilityFloorClaim;
+  return true;
+}
+
+/**
+ * Complete the in-process half of the first-upgrade transaction. The managed
+ * runtime calls this synchronously under its operation lock after floor 4 is
+ * durable and before it removes activationPending, so task admission cannot
+ * observe a value-only feature state between those two commits.
+ */
+export function completeProjectEnvBindingCapabilityAfterRuntimeActivation(): void {
+  if (!PROJECT_ENV_BINDINGS_ENABLED || capabilityReady) return;
+  if (capabilityFloorClaim === null || !capabilityFloorClaimFailed) {
+    throw new Error(
+      "project env capability has no failed activation claim to complete",
+    );
+  }
+  capabilityFloorClaim = Promise.resolve();
+  capabilityFloorClaimFailed = false;
+  capabilityReady = true;
+}
+
+/** One nullable bundle makes the feature id and its required policy epochs an
+ * atomic advertisement, and is also TaskUp's release admission switch. */
+export function projectEnvBindingCapability(): {
+  feature: string;
+  policyEpochs: number[];
+} | null {
+  return PROJECT_ENV_BINDINGS_ENABLED && capabilityReady
+    ? {
+        feature: PROJECT_ENV_BINDINGS_PROTOCOL_FEATURE,
+        policyEpochs: [...PROJECT_ENV_POLICY_EPOCHS],
+      }
+    : null;
+}

package/lib/project-env-loader.ts

@@ -0,0 +1,237 @@
+/**
+ * ADR-153 project-env resolution and shell-document rendering.
+ *
+ * This module is the one value-bearing seam between the encrypted host store
+ * and a task's authenticated loopback gateway. It keeps one rendered snapshot
+ * in memory and invalidates it synchronously with project-value mutations, so
+ * a rotation or deletion is visible to the next command without a restart.
+ */
+
+import { createHash } from "node:crypto";
+
+import {
+  getDecryptedForProject,
+  isReservedTaskEnvName,
+  projectEnvRevision,
+} from "./host-env";
+import type { TaskEnvView } from "./project-env-task-policy";
+import type { TaskProjectEnvSpec } from "./runtime-state";
+import type {
+  TaskGatewayEnvResolver,
+  TaskGatewayEnvSnapshot,
+} from "./task-gateway-state";
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export interface ResolvedTaskProjectEnv {
+  /** Only currently-delivered names. A deleted name disappears on refresh. */
+  readonly values: Readonly<Record<string, string>>;
+}
+
+/**
+ * Where a task's project values come from (ADR-153 §6, "Reconciling a
+ * runner"): one snapshot's view of the store; nothing at all, while the
+ * store is unreconciled or a read of it failed; or, only for a build whose
+ * store predates records, the stored values as they are. `none` never falls
+ * back to the stored values.
+ */
+export type TaskEnvSource =
+  | { kind: "view"; view: TaskEnvView }
+  | { kind: "none" }
+  | { kind: "stored" };
+
+const STORED: TaskEnvSource = { kind: "stored" };
+
+function compareAscii(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function previewNameAllowed(name: string): boolean {
+  // UAI_EDITOR_THEME is a cloud-owned non-secret task literal consumed once
+  // while seeding the editor. Every other reserved name remains host-owned.
+  return name === "UAI_EDITOR_THEME" || !isReservedTaskEnvName(name);
+}
+
+/**
+ * Resolve lead-project precedence before applying that row's declaration.
+ * With the task's view (ADR-153 §4), that view is the only source of project
+ * values: each delivered key's value as of its decision's head, from one
+ * snapshot of the store, never a separate read of the store here. The view
+ * already applied ownership and policy to the live records, so the names
+ * frozen into the task at launch do not filter it: a key added since reaches
+ * the next command, as a changed one does. With `none`, there are no project
+ * values at all.
+ */
+export function resolveTaskProjectEnv(
+  spec: TaskProjectEnvSpec,
+  source: TaskEnvSource = STORED,
+): ResolvedTaskProjectEnv {
+  const view = source.kind === "view" ? source.view : null;
+  const selected: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  const claimed = new Set<string>();
+  const projects = [...spec.projects].sort(
+    (left, right) =>
+      left.position - right.position ||
+      compareAscii(left.projectId, right.projectId),
+  );
+
+  if (view !== null) {
+    for (const policy of view.policies) {
+      if (policy.kind !== "deliver") continue;
+      const value = Object.hasOwn(view.values, policy.key) ? view.values[policy.key] : undefined;
+      const project = projects.find((candidate) => candidate.projectId === policy.projectId);
+      if (
+        value === undefined ||
+        project === undefined ||
+        !ENV_NAME.test(policy.key) ||
+        isReservedTaskEnvName(policy.key) ||
+        value.includes("\0")
+      ) {
+        continue;
+      }
+      selected[policy.key] = value;
+    }
+  }
+
+  for (const project of source.kind === "stored" ? projects : []) {
+    const stored = getDecryptedForProject(project.projectId);
+    const declared = new Set(project.declaredNames);
+    for (const [name, value] of Object.entries(stored)) {
+      if (
+        claimed.has(name) ||
+        !ENV_NAME.test(name) ||
+        isReservedTaskEnvName(name)
+      ) {
+        continue;
+      }
+      // The first stored row owns this key even when that project's schema
+      // does not declare it. Falling through would pair a later project's
+      // declaration with a different project's value, violating ADR-153's
+      // one-authority-unit rule.
+      claimed.add(name);
+      if (!declared.has(name)) continue;
+      if (typeof value !== "string" || value.includes("\0")) continue;
+      selected[name] = value;
+    }
+  }
+
+  // Preview/theme literals are task-scoped and intentionally win a collision
+  // with project env, matching the pre-loader Compose contract.
+  for (const [name, value] of Object.entries(spec.previewEnv)) {
+    if (
+      ENV_NAME.test(name) &&
+      previewNameAllowed(name) &&
+      !value.includes("\0")
+    ) {
+      selected[name] = value;
+    }
+  }
+  return { values: selected };
+}
+
+/** POSIX single-quote syntax, valid in dash, bash and zsh. */
+export function quoteTaskEnvValue(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Render the complete document validated by env-hook.sh. The digest covers
+ * the value-bearing prefix; its raw hex is repeated only in the terminal
+ * sentinel, while HTTP receives the quoted strong ETag.
+ */
+export function renderTaskProjectEnv(
+  resolved: ResolvedTaskProjectEnv,
+): TaskGatewayEnvSnapshot {
+  const names = Object.keys(resolved.values).sort(compareAscii);
+  let prefix = `# uai-env-v1 keys=${names.join(" ")}\n`;
+  for (const name of names) {
+    prefix += `export ${name}=${quoteTaskEnvValue(resolved.values[name] ?? "")}\n`;
+  }
+  const revision = createHash("sha256").update(prefix, "utf8").digest("hex");
+  return {
+    body: `${prefix}# uai-env-v1 end=${revision}\n`,
+    etag: `"${revision}"`,
+  };
+}
+
+/**
+ * Resolver closure installed on a durable task-gateway generation. The
+ * rendered snapshot stays in memory while every project used by the task has
+ * the same value revision. A set, delete, or credential-store reconcile bumps
+ * that project's revision synchronously, so the next request recomputes and
+ * still observes rotations and removals immediately.
+ *
+ * `uaiEnv` is the runner's own env for the task (the secrets proxy's trust
+ * variables while it runs), read per request: reserved names only, so it
+ * never collides with a project value, and its change re-renders too.
+ *
+ * `proxiedEnv` is the task's proxy-mode keys (ADR-153): each such name is
+ * withheld from the project values, and carries its placeholder only while
+ * the key is usable. Also read per request, and part of the cache key, so a
+ * change of readiness alone (pins in, pins failed) re-renders.
+ */
+export function taskProjectEnvResolver(
+  spec: TaskProjectEnvSpec,
+  uaiEnv: () => Readonly<Record<string, string>> = () => ({}),
+  proxiedEnv: () => {
+    readonly withheld: readonly string[];
+    readonly placeholders: Readonly<Record<string, string>>;
+  } = () => ({ withheld: [], placeholders: {} }),
+  taskSource: () => TaskEnvSource = () => STORED,
+): TaskGatewayEnvResolver {
+  const projectIds = [...new Set(spec.projects.map((project) => project.projectId))];
+  let revisions: number[] | undefined;
+  let runnerKey: string | undefined;
+  let snapshot: TaskGatewayEnvSnapshot | undefined;
+
+  return () => {
+    const currentRevisions = projectIds.map(projectEnvRevision);
+    const currentUai = uaiEnv();
+    const currentProxied = proxiedEnv();
+    const currentSource = taskSource();
+    const currentRunnerKey = JSON.stringify([
+      Object.entries(currentUai).sort(([a], [b]) => compareAscii(a, b)),
+      [...currentProxied.withheld].sort(compareAscii),
+      Object.entries(currentProxied.placeholders).sort(([a], [b]) => compareAscii(a, b)),
+      // The source, and a view's decisions and heads, never its values: a
+      // head that moves re-renders.
+      currentSource.kind === "view" ? [currentSource.kind, currentSource.view.policies] : [currentSource.kind],
+    ]);
+    if (
+      snapshot &&
+      runnerKey === currentRunnerKey &&
+      revisions?.length === currentRevisions.length &&
+      revisions.every((revision, index) => revision === currentRevisions[index])
+    ) {
+      return snapshot;
+    }
+
+    const resolved = resolveTaskProjectEnv(spec, currentSource);
+    const values: Record<string, string> = Object.create(null) as Record<string, string>;
+    Object.assign(values, resolved.values);
+    const withheld = new Set([
+      ...currentProxied.withheld,
+      ...(currentSource.kind === "view" ? currentSource.view.notDelivered : []),
+    ]);
+    for (const name of withheld) delete values[name];
+    // With no project env at all, no placeholder stands in for one either.
+    const placeholders = currentSource.kind === "none" ? {} : currentProxied.placeholders;
+    for (const [name, placeholder] of Object.entries(placeholders)) {
+      // Only in place of a withheld proxy-mode value, never a new name.
+      if (withheld.has(name) && ENV_NAME.test(name) && !isReservedTaskEnvName(name) && !placeholder.includes("\0")) {
+        values[name] = placeholder;
+      }
+    }
+    for (const [name, value] of Object.entries(currentUai)) {
+      // Only reserved names: Uai's own variables, never a project's.
+      if (ENV_NAME.test(name) && isReservedTaskEnvName(name) && !value.includes("\0")) values[name] = value;
+    }
+    snapshot = renderTaskProjectEnv({ values });
+    revisions = currentRevisions;
+    runnerKey = currentRunnerKey;
+    return snapshot;
+  };
+}