@runuai/host 0.9.150 → 0.9.152

package/lib/managed-runtime.ts

@@ -36,6 +36,8 @@ import {
   BUNDLED_RUNTIME_CAPABILITY,
   BUNDLED_RUNTIME_ROOT,
   MANAGED_RUNTIME_CAPABILITY,
+  MANAGED_RUNTIME_CREDENTIALS,
+  MANAGED_RUNTIME_CREDENTIALS_VERSION,
   extractVerifiedRuntimeArchive,
   readVerifiedArtifactFile,
   type ResolvedRuntimeDescriptor,
@@ -43,6 +45,7 @@ import {
   type RuntimeCapabilityDescriptorV3,
   type RuntimeAssetManifest,
   validateManagedRuntimeCapabilityDescriptor,
+  validateManagedRuntimeCredentialsDescriptor,
   validateRuntimeAssetManifest,
   validateRuntimeCapabilityDescriptor,
   validateRuntimeDescriptor,
@@ -77,6 +80,10 @@ const APPLE_CONTAINER_PLUGINS = Object.freeze([
   "machine-apiserver",
 ]);
 
+/** ADR-154 §13: the activation authority's record, in the runner's data
+ *  directory (lib/credentials-activation-authority.ts). */
+export const CREDENTIALS_ACTIVATION_RECORD = "credentials-activation.json";
+
 export interface ManagedRuntimePaths {
   readonly home: string;
   readonly root: string;
@@ -93,6 +100,17 @@ export interface ManagedRuntimePaths {
    * task state. It lives outside version generations so pruning/rollback
    * cannot erase the evidence an older runtime must honor. */
   readonly minimumRuntimeCapability: string;
+  /** ADR-154 §13's second, independent floor, claimed when the runner's
+   * credentials move to the cloud. The runtime capability floor cannot mark
+   * that cutover (see MANAGED_RUNTIME_CREDENTIALS), and like it this lives
+   * outside every generation, beside it in the data directory, so it holds on
+   * a runner installed through npm too. */
+  readonly minimumCredentialsCapability: string;
+  /** ADR-154 §13's activation record, beside the runner's database: once it
+   * exists the runner has begun its switch to cloud credentials, which no
+   * release built before the cutover may undo, so it counts as a credentials
+   * floor of 1 even before that floor's own file is written. */
+  readonly credentialsActivationRecord: string;
   /** Older Phase-B builds may have claimed provider state before publishing
    * the durable capability marker. This preserved marker implies floor 2. */
   readonly runtimeProviderState: string;
@@ -295,6 +313,11 @@ export function managedRuntimePaths(home?: string): ManagedRuntimePaths {
       configuredUaiHome,
       ".minimum-runtime-capability.json",
     ),
+    minimumCredentialsCapability: path.join(
+      configuredUaiHome,
+      ".minimum-credentials-capability.json",
+    ),
+    credentialsActivationRecord: path.join(configuredDataDir, CREDENTIALS_ACTIVATION_RECORD),
     runtimeProviderState: path.join(configuredDataDir, "container-runtime-provider.json"),
     // The lock must not live inside `root`: uninstall atomically renames that
     // whole tree, and moving the lock would let another process create a new
@@ -464,6 +487,7 @@ export async function installManagedRuntimeArchive(
         nativePlatform,
       );
       await assertRuntimeMeetsDurableCapabilityFloor(paths, currentDescriptor);
+      await assertRuntimeMeetsDurableCredentialsFloor(paths, currentDescriptor);
       if (
         installIntent?.serviceOwnership === "legacy" &&
         !(await options.canActivate!({ legacyConversion: true }))
@@ -501,10 +525,12 @@ export async function installManagedRuntimeArchive(
         version: options.version,
         platform: options.platform,
       });
-      await assertRuntimeMeetsDurableCapabilityFloor(paths, {
+      const stagedDescriptor: ResolvedRuntimeDescriptor = {
         ...inspected.descriptor,
         ...inspected.capabilities,
-      });
+      };
+      await assertRuntimeMeetsDurableCapabilityFloor(paths, stagedDescriptor);
+      await assertRuntimeMeetsDurableCredentialsFloor(paths, stagedDescriptor);
       if (
         options.canActivate &&
         !(await options.canActivate(activationContext))
@@ -545,6 +571,7 @@ export async function installManagedRuntimeArchive(
             options.platform,
           );
           await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+          await assertRuntimeMeetsDurableCredentialsFloor(paths, targetDescriptor);
         } else {
           await rename(staged, target);
           await syncDirectory(paths.runtime);
@@ -716,6 +743,7 @@ export async function rollbackManagedRuntime(
       platform,
     );
     await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+    await assertRuntimeMeetsDurableCredentialsFloor(paths, targetDescriptor);
     if (canActivate && !(await canActivate())) {
       throw new Error("refusing to roll back while host tasks are active");
     }
@@ -810,7 +838,7 @@ async function persistManagedRuntimeCapabilityFloor(
   // owned file before making the floor durable, so standalone recovery can
   // recognize the new cross-platform capability marker immediately.
   const recoveryEntrypoint = await assertRecoveryEntrypointReplaceable(paths);
-  if (recoveryEntrypoint === "legacy-v1") {
+  if (recoveryEntrypoint === "legacy-v1" || recoveryEntrypoint === "legacy-v2") {
     await ensureRecoveryEntrypoint(paths);
   }
   await mkdir(path.dirname(paths.minimumRuntimeCapability), {
@@ -825,6 +853,178 @@ async function persistManagedRuntimeCapabilityFloor(
   });
 }
 
+/**
+ * ADR-154 §13's local commit: claim the credentials floor. From then on this
+ * release and every later one refuse to update to, roll back to, or boot a
+ * generation built before the cloud-only credentials cutover. It only rises,
+ * is written under the managed-operation lock, and is independent of the
+ * runtime capability floor, which cannot rise to mark the cutover.
+ *
+ * On a runner installed through npm there is no managed runtime: the floor is
+ * only persisted, nothing reads it yet, and the managed tree is not created.
+ *
+ * It refuses, and the activation authority retries, while an installation
+ * intent, an activation marker, a rollback journal or an uninstall marker is
+ * present, and while the selected generation itself predates the floor. Each
+ * of those means the generation this runner boots next may not be the one
+ * claiming, or is about to be removed, which is the window the runtime
+ * capability claim closes for the same reason. Refusing is safe because the
+ * local commit precedes the cloud commit: a failed claim leaves the runner on
+ * v0 with its stores intact. Standalone recovery (revision 3) enforces it
+ * too (see `recoveryEntrypointContents`).
+ */
+export async function claimCredentialsCapabilityFloor(
+  minimumCredentialsCapability: number = MANAGED_RUNTIME_CREDENTIALS_VERSION,
+  home?: string,
+): Promise<void> {
+  assertCredentialsCapabilityFloor(minimumCredentialsCapability);
+  const paths = managedRuntimePaths(home);
+  await withManagedOperationLockWaiting(paths, async () => {
+    await assertNoManagedInstallIntent(paths, "credentials capability claim");
+    if (
+      pathExistsSync(paths.activationPending) ||
+      pathExistsSync(paths.rollbackJournal)
+    ) {
+      throw new Error("managed runtime activation is already in progress");
+    }
+    if (pathExistsSync(paths.maintenancePending)) {
+      throw new Error("managed runtime maintenance is already in progress");
+    }
+    const install = await managedInstallState(paths);
+    if (install.kind === "damaged") throw new Error(install.detail);
+    if (install.kind === "selected") {
+      const selectedCapability = await resolveInstalledCredentialsCapability(
+        await realpath(path.join(paths.runtime, install.version)),
+      );
+      if (selectedCapability < minimumCredentialsCapability) {
+        throw new Error(
+          `refusing to claim credentials capability ${minimumCredentialsCapability}; the selected managed runtime ${install.version} carries credentials capability ${selectedCapability}`,
+        );
+      }
+      // Standalone recovery must refuse what this floor refuses before the
+      // floor counts.
+      await ensureCurrentRecoveryEntrypoint(paths);
+    }
+    await mkdir(path.dirname(paths.minimumCredentialsCapability), {
+      recursive: true,
+      mode: 0o700,
+    });
+    const existing = await readMinimumCredentialsCapabilityFile(paths);
+    if (existing !== null && existing >= minimumCredentialsCapability) return;
+    await writeAtomicJson(paths.minimumCredentialsCapability, {
+      schemaVersion: 1,
+      minimumCredentialsCapability,
+    });
+  });
+}
+
+/** Whether the credentials floor's file exists, valid or not: a runner
+ *  that claimed it has begun its switch, whatever its activation record
+ *  says (ADR-154 §13). */
+export function credentialsCapabilityFloorExists(home?: string): boolean {
+  return pathExistsSync(managedRuntimePaths(home).minimumCredentialsCapability);
+}
+
+/**
+ * ADR-154 §13, the runner's local commit: from its record on, the switch
+ * never goes back, so no release built before the cutover may boot here
+ * again. Under the managed-operation lock, which every install, update and
+ * rollback holds from its checks to its link commit, so none crosses this:
+ * nothing is being installed, activated, rolled back or uninstalled; the
+ * selected generation carries the credentials marker, so the next boot is a
+ * release that reads the record; standalone recovery reads it too (its
+ * entrypoint upgraded); then `record()` writes the record, still under the
+ * lock. An update or rollback after it finds the record a credentials floor.
+ * A managed tree that is damaged (its current link dangling or missing
+ * beside other managed state) fails closed. A runner with no managed
+ * install (an npm one) has none of this: `record()` alone.
+ *
+ * Standalone recovery takes no lock: it reads the record when it starts,
+ * then hands the command to the previous generation's own launcher, which
+ * does not. The upgrade here fences that launcher's rollback: every managed
+ * release before the cutover rolls back under this lock only, and before
+ * its journal or any link refuses a recovery entrypoint other than its own
+ * revisions'. So such a rollback either took the lock first, and this finds
+ * its generation selected, or comes after the upgrade and refuses.
+ */
+export async function commitCredentialsSwitchLocally(record: () => void, home?: string): Promise<void> {
+  const paths = managedRuntimePaths(home);
+  await withManagedOperationLockWaiting(paths, async () => {
+    await assertNoManagedInstallIntent(paths, "the switch to cloud credentials");
+    const install = await managedInstallState(paths);
+    if (install.kind === "damaged") throw new Error(install.detail);
+    if (install.kind === "selected") {
+      if (pathExistsSync(paths.activationPending) || pathExistsSync(paths.rollbackJournal)) {
+        throw new Error("managed runtime activation is already in progress");
+      }
+      if (pathExistsSync(paths.maintenancePending)) {
+        throw new Error("managed runtime maintenance is already in progress");
+      }
+      const capability = await resolveInstalledCredentialsCapability(
+        await realpath(path.join(paths.runtime, install.version)),
+      );
+      if (capability < MANAGED_RUNTIME_CREDENTIALS_VERSION) {
+        throw new Error(
+          `the selected managed runtime ${install.version} was built before the switch to cloud credentials`,
+        );
+      }
+      await ensureCurrentRecoveryEntrypoint(paths);
+    }
+    record();
+  });
+}
+
+type ManagedInstallState =
+  | { kind: "absent" }
+  | { kind: "selected"; version: string }
+  | { kind: "damaged"; detail: string };
+
+/** A managed install, if any, and the generation it boots next. A missing or
+ *  dangling current link is no npm install when other managed state (the
+ *  runtime directory, a previous link, the recovery entrypoint) is there:
+ *  that tree is damaged, and nothing may be decided from it. */
+async function managedInstallState(paths: ManagedRuntimePaths): Promise<ManagedInstallState> {
+  let currentLink = true;
+  try {
+    await lstat(paths.current);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+    currentLink = false;
+  }
+  if (currentLink) {
+    const version = await readVersionLink(paths.current, paths.runtime);
+    return version === null
+      ? { kind: "damaged", detail: "the managed runtime's current link leads to nothing; repair it first" }
+      : { kind: "selected", version };
+  }
+  for (const [state, what] of [
+    [paths.runtime, "runtime directory"],
+    [paths.previous, "previous runtime link"],
+    [paths.recoveryEntrypoint, "recovery entrypoint"],
+  ] as const) {
+    try {
+      await lstat(state);
+      return { kind: "damaged", detail: `the managed runtime has a ${what} but no current runtime; repair it first` };
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+  }
+  return { kind: "absent" };
+}
+
+/** The caller holds the operation lock and the runtime is managed. */
+async function ensureCurrentRecoveryEntrypoint(paths: ManagedRuntimePaths): Promise<void> {
+  if ((await assertRecoveryEntrypointReplaceable(paths)) !== "current") {
+    await ensureRecoveryEntrypoint(paths);
+  }
+}
+
+function assertCredentialsCapabilityFloor(minimum: number): void {
+  if (!Number.isSafeInteger(minimum) || minimum < 1) {
+    throw new Error("managed runtime credentials floor is invalid");
+  }
+}
+
 /** True while `current` has changed but the supervisor has not exec'd it yet. */
 export function managedRuntimeActivationPending(home?: string): boolean {
   return pathExistsSync(managedRuntimePaths(home).activationPending);
@@ -1122,6 +1322,7 @@ async function reconcileManagedRuntimeSelectionLocked(
         selectedVersion,
       );
       await assertRuntimeMeetsDurableCapabilityFloor(paths, selectedDescriptor);
+      await assertRuntimeMeetsDurableCredentialsFloor(paths, selectedDescriptor);
     }
     const persistAcknowledgedCapabilityFloor = async (): Promise<void> => {
       if (capabilityAcknowledgement === null) return;
@@ -1978,7 +2179,13 @@ async function resolveInstalledRuntimeCapabilities(
       root,
       platformCapabilities.capabilitySchemaVersion,
     );
-  return { ...platformCapabilities, runtimeCapabilityVersion };
+  const credentialsCapabilityVersion =
+    await resolveInstalledCredentialsCapability(root);
+  return {
+    ...platformCapabilities,
+    runtimeCapabilityVersion,
+    credentialsCapabilityVersion,
+  };
 }
 
 async function resolveInstalledPlatformCapabilities(
@@ -2051,6 +2258,39 @@ async function resolveInstalledManagedRuntimeCapability(
     .capabilitySchemaVersion;
 }
 
+/** `root` must already be the generation's real path. */
+async function resolveInstalledCredentialsCapability(
+  root: string,
+): Promise<number> {
+  const descriptorPath = path.join(
+    root,
+    ...MANAGED_RUNTIME_CREDENTIALS.split("/"),
+  );
+  let metadata;
+  try {
+    metadata = await lstat(descriptorPath);
+  } catch (error) {
+    if (isMissing(error)) return 0;
+    throw error;
+  }
+  if (
+    !metadata.isFile() ||
+    metadata.isSymbolicLink() ||
+    metadata.size > MAX_OPERATION_LOCK_BYTES ||
+    !isInside(root, await realpath(descriptorPath))
+  ) {
+    throw new Error("managed runtime credentials descriptor is invalid");
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(descriptorPath, "utf8"));
+  } catch {
+    throw new Error("managed runtime credentials descriptor is invalid JSON");
+  }
+  return validateManagedRuntimeCredentialsDescriptor(raw)
+    .credentialsCapabilityVersion;
+}
+
 async function validateInstalledRuntimeAssets(
   root: string,
   capabilities: RuntimeCapabilityDescriptorV3,
@@ -2646,7 +2886,7 @@ async function ensureRecoveryEntrypoint(paths: ManagedRuntimePaths): Promise<voi
   }
 }
 
-type RecoveryEntrypointState = "missing" | "legacy-v1" | "current";
+type RecoveryEntrypointState = "missing" | "legacy-v1" | "legacy-v2" | "current";
 
 /** Classify only entrypoints this release owns exactly. */
 async function assertRecoveryEntrypointReplaceable(
@@ -2669,6 +2909,9 @@ async function assertRecoveryEntrypointReplaceable(
     if (existing.equals(Buffer.from(recoveryEntrypointContents(paths, 1)))) {
       return "legacy-v1";
     }
+    if (existing.equals(Buffer.from(recoveryEntrypointContents(paths, 2)))) {
+      return "legacy-v2";
+    }
     throw new Error(
       `refusing to replace modified host recovery entrypoint at ${paths.recoveryEntrypoint}`,
     );
@@ -2678,13 +2921,57 @@ async function assertRecoveryEntrypointReplaceable(
   }
 }
 
+/**
+ * The standalone recovery shell. Revision 3 enforces ADR-154's credentials
+ * floor too: once the activation record or the credentials floor exists, a
+ * previous generation without the credentials marker (built before the
+ * cutover) is refused, so recovery cannot undo a switch to cloud credentials,
+ * even between the runner's local commit and the cloud's. Any change to these
+ * bytes makes a deployed entrypoint "modified", so each revision is a new one
+ * that this release's floors upgrade the older owned revisions to before they
+ * count (commitCredentialsSwitchLocally, claimCredentialsCapabilityFloor).
+ */
 function recoveryEntrypointContents(
   paths: ManagedRuntimePaths,
-  revision: 1 | 2 = 2,
+  revision: 1 | 2 | 3 = 3,
 ): string {
   const runtime = shellSingleQuote(paths.runtime);
   const capabilityFloor = shellSingleQuote(paths.minimumRuntimeCapability);
   const providerState = shellSingleQuote(paths.runtimeProviderState);
+  const credentialsGuard =
+    revision < 3
+      ? ""
+      : `credentials_floor=${shellSingleQuote(paths.minimumCredentialsCapability)}
+activation_record=${shellSingleQuote(paths.credentialsActivationRecord)}
+required_credentials=0
+if [ -e "$credentials_floor" ] || [ -L "$credentials_floor" ]; then
+  if [ ! -f "$credentials_floor" ] || [ -L "$credentials_floor" ]; then
+    fail "the credentials floor is invalid"
+  fi
+  required_credentials=$(LC_ALL=C tr -d '[:space:]' < "$credentials_floor" |
+    sed -n 's/^{"schemaVersion":1,"minimumCredentialsCapability":\\([1-9][0-9]*\\)}$/\\1/p')
+  case $required_credentials in
+    '' | *[!0-9]*) fail "the credentials floor is invalid" ;;
+  esac
+fi
+if [ "$required_credentials" -lt 1 ] && { [ -e "$activation_record" ] || [ -L "$activation_record" ]; }; then
+  required_credentials=1
+fi
+if [ "$required_credentials" -ge 1 ]; then
+  credentials=$generation/agent/managed-runtime-credentials.json
+  if [ ! -f "$credentials" ] || [ -L "$credentials" ]; then
+    fail "the previous runtime predates this host's switch to cloud credentials"
+  fi
+  generation_credentials=$(LC_ALL=C tr -d '[:space:]' < "$credentials" |
+    sed -n 's/^{"credentialsCapabilityVersion":\\([1-9][0-9]*\\)}$/\\1/p')
+  case $generation_credentials in
+    '' | *[!0-9]*) fail "the previous runtime credentials descriptor is invalid" ;;
+  esac
+  if [ "$generation_credentials" -lt "$required_credentials" ]; then
+    fail "the previous runtime predates this host's switch to cloud credentials"
+  fi
+fi
+`;
   const capabilityProbe =
     revision === 1
       ? `  capability=$generation/agent/bundled-runtime/capability.json
@@ -2800,7 +3087,7 @@ ${capabilityProbe}  case $generation_capability in
     fail "the previous runtime capability $generation_capability is below this host's floor $required_floor"
   fi
 fi
-launcher_dir=$generation/bin
+${credentialsGuard}launcher_dir=$generation/bin
 if [ ! -d "$launcher_dir" ] || [ -L "$launcher_dir" ]; then
   fail "the previous managed runtime launcher directory is invalid"
 fi
@@ -2813,6 +3100,14 @@ exec "$launcher" "$@"
 `;
 }
 
+/** Tests only: an exact revision's bytes, as it was or is deployed. */
+export function recoveryEntrypointContentsForTests(
+  paths: ManagedRuntimePaths,
+  revision: 1 | 2 | 3,
+): string {
+  return recoveryEntrypointContents(paths, revision);
+}
+
 function shellSingleQuote(value: string): string {
   return `'${value.split("'").join(`'"'"'`)}'`;
 }
@@ -2936,6 +3231,7 @@ async function recoverRollback(
     journal.version,
   );
   await assertRuntimeMeetsDurableCapabilityFloor(paths, targetDescriptor);
+  await assertRuntimeMeetsDurableCredentialsFloor(paths, targetDescriptor);
   await atomicVersionLink(paths.current, journal.version);
   await atomicVersionLink(paths.previous, journal.fromVersion);
   await writeRollbackUpdateHold(paths, journal.fromVersion, journal.version);
@@ -2955,6 +3251,74 @@ async function assertRuntimeMeetsDurableCapabilityFloor(
   }
 }
 
+/** Before the switch every generation passes, exactly as before the cutover. */
+async function assertRuntimeMeetsDurableCredentialsFloor(
+  paths: ManagedRuntimePaths,
+  descriptor: ResolvedRuntimeDescriptor,
+): Promise<void> {
+  const minimum = await requiredCredentialsCapability(paths);
+  if (minimum !== null && descriptor.credentialsCapabilityVersion < minimum) {
+    throw new Error(
+      `refusing runtime ${descriptor.hostVersion} with credentials capability ${descriptor.credentialsCapabilityVersion}; this host requires credentials capability ${minimum} since its credentials moved to the cloud`,
+    );
+  }
+}
+
+/** The credentials floor in force: its file's, and at least 1 once the
+ *  activation record exists (the switch has begun). */
+async function requiredCredentialsCapability(paths: ManagedRuntimePaths): Promise<number | null> {
+  const floor = await readMinimumCredentialsCapabilityFile(paths);
+  let recorded = false;
+  try {
+    await lstat(paths.credentialsActivationRecord);
+    recorded = true;
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+  if (!recorded) return floor;
+  return Math.max(floor ?? 0, 1);
+}
+
+async function readMinimumCredentialsCapabilityFile(
+  paths: ManagedRuntimePaths,
+): Promise<number | null> {
+  let bytes: string;
+  try {
+    const stat = await lstat(paths.minimumCredentialsCapability);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.size > MAX_OPERATION_LOCK_BYTES
+    ) {
+      throw new Error("managed runtime credentials floor is invalid");
+    }
+    bytes = await readFile(paths.minimumCredentialsCapability, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes);
+  } catch {
+    throw new Error("managed runtime credentials floor is invalid");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("managed runtime credentials floor is invalid");
+  }
+  const marker = raw as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["minimumCredentialsCapability", "schemaVersion"].join("\0") ||
+    marker.schemaVersion !== 1 ||
+    !Number.isSafeInteger(marker.minimumCredentialsCapability) ||
+    Number(marker.minimumCredentialsCapability) < 1
+  ) {
+    throw new Error("managed runtime credentials floor is invalid");
+  }
+  return Number(marker.minimumCredentialsCapability);
+}
+
 async function readMinimumRuntimeCapability(
   paths: ManagedRuntimePaths,
 ): Promise<number | null> {