@runuai/host 0.9.110 → 0.9.111

package/db/migrations/0019_engine_account_store_ref.sql

@@ -0,0 +1,3 @@
+-- ADR-134 (host 0.9.111): the credential-store parameter an engine account
+-- mirrors to. Null on owned hosts and before the first successful mirror.
+ALTER TABLE `host_engine_accounts` ADD `store_ref` text;

package/db/migrations/meta/_journal.json

@@ -134,6 +134,13 @@
       "when": 1788900000000,
       "tag": "0018_engine_account_position",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "6",
+      "when": 1788900000001,
+      "tag": "0019_engine_account_store_ref",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -281,6 +281,10 @@ export const engineAccounts = sqliteTable("host_engine_accounts", {
   // Manage-v1: priority within (scope, kind) — tasks pick the first healthy
   // account in ascending position; ties break on created_at.
   position: integer("position", { mode: "number" }).notNull().default(0),
+  // ADR-134: the credential-store parameter this row mirrors to (null on an
+  // owned host, or before the first successful mirror). The store is the
+  // truth when configured; this row is the local cache.
+  storeRef: text("store_ref"),
   createdAt: integer("created_at", { mode: "number" }).notNull(),
 });
 

package/lib/credential-store.ts

@@ -0,0 +1,285 @@
+/**
+ * Credential store (ADR-134) — where a Uai-operated host keeps tenant
+ * credentials: AWS Systems Manager Parameter Store, one SecureString per
+ * credential, encrypted with the `alias/uai-credentials` KMS key, read and
+ * written with the host's own IAM role through the `aws` CLI the host already
+ * uses for machines (ADR-121).
+ *
+ * Owned hosts never construct one of these: `configuredCredentialStore()`
+ * returns null unless `UAI_CREDENTIAL_STORE=aws-ssm`, and every caller treats
+ * null as "credentials stay on this machine".
+ *
+ * Secret material never travels on argv where `ps` would show it: a put
+ * writes its request to a 0600 file in a fresh 0700 temp dir and hands the CLI
+ * `--cli-input-json file://<path>`, removed as soon as the CLI exits. (Not
+ * `file:///dev/stdin`: the CLI opens the file twice and a pipe reads empty the
+ * second time — verified against aws-cli 2.33.) Nothing here logs a value.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { env } from "./env";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Parameter names: absolute, slash-separated, the SSM-legal character set. */
+const PARAMETER_NAME = /^\/[A-Za-z0-9_.\-]+(?:\/[A-Za-z0-9_.\-]+)*$/;
+/** A single path segment (an org id, a host id, an engine kind, an account id). */
+const PATH_SEGMENT = /^[A-Za-z0-9_.\-]+$/;
+
+export interface StoredParameter {
+  name: string;
+  value: string;
+}
+
+export interface CredentialStore {
+  readonly kind: "aws-ssm";
+  /** Create or overwrite one credential. Throws on failure. */
+  put(name: string, value: string): Promise<void>;
+  /** The credential's plaintext, or null when it does not exist. */
+  get(name: string): Promise<string | null>;
+  /** Idempotent: a missing parameter is not an error. */
+  delete(name: string): Promise<void>;
+  /** Every credential under `path` (recursive), decrypted. Throws on failure. */
+  list(path: string): Promise<StoredParameter[]>;
+}
+
+export interface CliResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** `aws --region <r> --output json <args>`. */
+export type AwsCliRunner = (args: string[]) => Promise<CliResult>;
+
+export function isParameterName(name: string): boolean {
+  return PARAMETER_NAME.test(name);
+}
+
+export function isParameterPathSegment(segment: string): boolean {
+  return PATH_SEGMENT.test(segment);
+}
+
+/** Join path segments under `prefix`, refusing anything SSM would reject or
+ *  that could escape its intended subtree (an empty segment, a `/` inside). */
+export function parameterName(prefix: string, ...segments: string[]): string {
+  for (const segment of segments) {
+    if (!isParameterPathSegment(segment)) {
+      throw new Error(`invalid credential-store path segment: ${JSON.stringify(segment)}`);
+    }
+  }
+  const name = `${prefix}/${segments.join("/")}`;
+  if (!isParameterName(name)) {
+    throw new Error(`invalid credential-store parameter name: ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+
+export function defaultAwsCliRunner(region: string): AwsCliRunner {
+  return (args) =>
+    new Promise<CliResult>((resolve) => {
+      let stdout = "";
+      let stderr = "";
+      let settled = false;
+      const child = spawn("aws", ["--region", region, "--output", "json", ...args], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      const settle = (status: number | null): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ status, stdout, stderr });
+      };
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        const grace = setTimeout(() => settle(null), 2_000);
+        grace.unref?.();
+      }, DEFAULT_TIMEOUT_MS);
+      timer.unref?.();
+      child.stdout?.setEncoding("utf8");
+      child.stderr?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk: string) => (stdout += chunk));
+      child.stderr?.on("data", (chunk: string) => (stderr += chunk));
+      child.once("error", () => settle(null));
+      child.once("close", (code) => settle(code));
+    });
+}
+
+/** Run `work` with a 0600 file holding `content`, inside a private temp dir
+ *  that is removed afterwards whatever happens. */
+async function withPrivateInputFile<T>(
+  content: string,
+  work: (path: string) => Promise<T>,
+): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "uai-credential-store-"));
+  try {
+    const path = join(dir, "input.json");
+    writeFileSync(path, content, { mode: 0o600 });
+    return await work(path);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function isNotFound(result: CliResult): boolean {
+  return /ParameterNotFound/.test(result.stderr);
+}
+
+/** Summarize a CLI failure WITHOUT echoing stdout (which could carry a value). */
+function failure(op: string, result: CliResult): Error {
+  const line =
+    result.stderr
+      .split("\n")
+      .map((l) => l.trim())
+      .find((l) => l.length > 0) ?? (result.status === null ? "spawn failed or timed out" : "");
+  return new Error(`aws ssm ${op} failed (exit ${result.status ?? "none"}): ${line}`);
+}
+
+export interface AwsSsmCredentialStoreOptions {
+  region: string;
+  kmsKeyId: string;
+  runner?: AwsCliRunner;
+}
+
+export class AwsSsmCredentialStore implements CredentialStore {
+  readonly kind = "aws-ssm" as const;
+  private readonly run: AwsCliRunner;
+  private readonly kmsKeyId: string;
+
+  constructor(opts: AwsSsmCredentialStoreOptions) {
+    this.run = opts.runner ?? defaultAwsCliRunner(opts.region);
+    this.kmsKeyId = opts.kmsKeyId;
+  }
+
+  async put(name: string, value: string): Promise<void> {
+    if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
+    // Tier Advanced: a Codex auth.json is ~4 KB, past the 4 KB standard cap.
+    // Tags cannot ride along with Overwrite, and the path already encodes
+    // ownership, so none are set.
+    const input = JSON.stringify({
+      Name: name,
+      Value: value,
+      Type: "SecureString",
+      KeyId: this.kmsKeyId,
+      Tier: "Advanced",
+      Overwrite: true,
+    });
+    const result = await withPrivateInputFile(input, (path) =>
+      this.run(["ssm", "put-parameter", "--cli-input-json", `file://${path}`]),
+    );
+    if (result.status !== 0) throw failure("put-parameter", result);
+  }
+
+  async get(name: string): Promise<string | null> {
+    if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
+    const result = await this.run([
+      "ssm",
+      "get-parameter",
+      "--name",
+      name,
+      "--with-decryption",
+    ]);
+    if (result.status !== 0) {
+      if (isNotFound(result)) return null;
+      throw failure("get-parameter", result);
+    }
+    const parsed = JSON.parse(result.stdout) as { Parameter?: { Value?: unknown } };
+    const value = parsed.Parameter?.Value;
+    if (typeof value !== "string") throw new Error("aws ssm get-parameter: malformed response");
+    return value;
+  }
+
+  async delete(name: string): Promise<void> {
+    if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
+    const result = await this.run(["ssm", "delete-parameter", "--name", name]);
+    if (result.status !== 0 && !isNotFound(result)) {
+      throw failure("delete-parameter", result);
+    }
+  }
+
+  async list(path: string): Promise<StoredParameter[]> {
+    if (!isParameterName(path)) throw new Error(`invalid parameter path: ${path}`);
+    const out: StoredParameter[] = [];
+    let nextToken: string | undefined;
+    // The CLI auto-paginates JSON output, but a response may still carry a
+    // NextToken when the page cap is hit; follow it either way.
+    for (let page = 0; page < 100; page++) {
+      const result = await this.run([
+        "ssm",
+        "get-parameters-by-path",
+        "--path",
+        path,
+        "--recursive",
+        "--with-decryption",
+        ...(nextToken ? ["--next-token", nextToken] : []),
+      ]);
+      if (result.status !== 0) throw failure("get-parameters-by-path", result);
+      const parsed = JSON.parse(result.stdout) as {
+        Parameters?: Array<{ Name?: unknown; Value?: unknown }>;
+        NextToken?: unknown;
+      };
+      for (const p of parsed.Parameters ?? []) {
+        if (typeof p.Name === "string" && typeof p.Value === "string") {
+          out.push({ name: p.Name, value: p.Value });
+        }
+      }
+      if (typeof parsed.NextToken === "string" && parsed.NextToken) {
+        nextToken = parsed.NextToken;
+      } else {
+        break;
+      }
+    }
+    return out;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Process-wide configuration.
+// ---------------------------------------------------------------------------
+
+let override: CredentialStore | null | undefined;
+let configured: CredentialStore | null | undefined;
+let warnedMissingRegion = false;
+
+/** Tests: pin the store (`null` = behave as an owned host); `undefined` resets. */
+export function setCredentialStoreOverride(store: CredentialStore | null | undefined): void {
+  override = store;
+}
+
+/** The parameter-name prefix every stored credential lives under. */
+export function credentialStorePrefix(): string {
+  return env.UAI_CREDENTIAL_STORE_PREFIX;
+}
+
+/**
+ * The store this host mirrors to, or null on an owned host (the default).
+ * Memoized: the env does not change while the process runs.
+ */
+export function configuredCredentialStore(): CredentialStore | null {
+  if (override !== undefined) return override;
+  if (configured !== undefined) return configured;
+  if (env.UAI_CREDENTIAL_STORE !== "aws-ssm") {
+    configured = null;
+    return configured;
+  }
+  const region = env.UAI_AWS_REGION;
+  if (!region) {
+    if (!warnedMissingRegion) {
+      warnedMissingRegion = true;
+      console.warn(
+        "[credential-store] UAI_CREDENTIAL_STORE=aws-ssm needs UAI_AWS_REGION; credentials stay local until it is set",
+      );
+    }
+    configured = null;
+    return configured;
+  }
+  configured = new AwsSsmCredentialStore({
+    region,
+    kmsKeyId: env.UAI_CREDENTIAL_STORE_KMS_KEY,
+  });
+  return configured;
+}

package/lib/engine-accounts.ts

@@ -27,12 +27,27 @@ import {
   isEngineAccountScope,
   isEngineAccountLabel,
 } from "../src/protocol";
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { eq } from "drizzle-orm";
 
+import {
+  configuredCredentialStore,
+  credentialStorePrefix,
+  isParameterPathSegment,
+  parameterName,
+  type CredentialStore,
+} from "./credential-store";
 import { getDb, schema } from "./db";
 import {
   taskContainerBackend,
@@ -762,6 +777,7 @@ export function addEngineAccount(
         position: nextPosition(kind, scope),
       })
       .run();
+    mirrorEngineAccount(id);
     return { ok: true, message: `Added Claude account "${trimmedLabel}".`, id };
   }
 
@@ -781,6 +797,7 @@ export function addEngineAccount(
         position: nextPosition(kind, scope),
       })
       .run();
+    mirrorEngineAccount(id);
     return {
       ok: true,
       message: `Added ${API_KEY_ENGINE_LABELS[kind] ?? kind} account "${trimmedLabel}".`,
@@ -827,6 +844,7 @@ export function addEngineAccount(
         position: nextPosition(kind, scope),
       })
       .run();
+    mirrorEngineAccount(id);
     return { ok: true, message: `Added Codex account "${trimmedLabel}".`, id };
   }
 
@@ -924,6 +942,7 @@ function addConfigDirAccountFromAuthJson(
       position: nextPosition(kind, scope),
     })
     .run();
+  mirrorEngineAccount(id);
   return { ok: true, message: `Added ${engineLabel} account "${trimmedLabel}".`, id };
 }
 
@@ -960,14 +979,12 @@ export function removeEngineAccount(
   if (!accountRemovableInScope(row, scope)) {
     return { ok: false, message: "That account belongs to a different scope." };
   }
-  getDb().delete(schema.engineAccounts).where(eq(schema.engineAccounts.id, id)).run();
-  if (row.authKind === "config-dir" && row.configDir) {
-    try {
-      rmSync(row.configDir, { recursive: true, force: true });
-    } catch {
-      /* best effort — the DB row is gone, which is what matters */
-    }
-  }
+  removeLocalAccountRow(row);
+  // ADR-134: the parameter goes too, best effort; the row is already gone.
+  queueStoreWrite(`delete ${id}`, async (store) => {
+    const name = row.storeRef ?? engineAccountParameterName(row);
+    if (name) await store.delete(name);
+  });
   return { ok: true, message: `Removed "${row.label}".` };
 }
 
@@ -998,6 +1015,7 @@ export function renameEngineAccount(
     .set({ label: trimmed })
     .where(eq(schema.engineAccounts.id, id))
     .run();
+  mirrorEngineAccount(id);
   return { ok: true, message: `Renamed to "${trimmed}".` };
 }
 
@@ -1043,5 +1061,390 @@ export function reorderEngineAccounts(
       .where(eq(schema.engineAccounts.id, id))
       .run();
   });
+  for (const id of ids) mirrorEngineAccount(id);
   return { ok: true, message: "Order saved." };
 }
+
+/** Delete a row and its isolated config dir (no store call). */
+function removeLocalAccountRow(row: {
+  id: string;
+  authKind: string;
+  configDir: string | null;
+}): void {
+  getDb().delete(schema.engineAccounts).where(eq(schema.engineAccounts.id, row.id)).run();
+  if (row.authKind === "config-dir" && row.configDir) {
+    try {
+      rmSync(row.configDir, { recursive: true, force: true });
+    } catch {
+      /* best effort — the DB row is gone, which is what matters */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credential store mirror (ADR-134, docs/credential-store.md).
+//
+// On a Uai-operated host the rows above are a CACHE of AWS Parameter Store:
+// every mutation mirrors its row (metadata + secret material) to one
+// parameter, and `reconcileEngineAccountsFromStore` at host start imports
+// what this host lacks, uploads rows that were never mirrored, and drops rows
+// whose parameter is gone. Task-up resolution never waits on the store.
+// On an owned host `configuredCredentialStore()` is null and none of this
+// runs — credentials never leave the machine.
+// ---------------------------------------------------------------------------
+
+/** The versioned JSON a parameter holds. Never logged. */
+export interface StoredEngineAccount {
+  v: 1;
+  id: string;
+  kind: string;
+  label: string;
+  authKind: AccountAuthKind;
+  scope: string;
+  position: number;
+  createdAt: number;
+  /** `env` accounts: the exec env the row injects. */
+  env?: Record<string, string>;
+  /** `config-dir` accounts: the dir's files by basename (today: auth.json). */
+  files?: Record<string, string>;
+}
+
+/** Largest single file mirrored from a config dir (Advanced tier is 8 KB total). */
+const MAX_STORED_FILE_BYTES = 8 * 1024;
+
+type StoreRow = {
+  id: string;
+  kind: string;
+  label: string;
+  authKind: string;
+  secretEnc: string | null;
+  configDir: string | null;
+  scope?: string | null;
+  position?: number | null;
+  storeRef?: string | null;
+  createdAt: number;
+};
+
+let storeHostId: string | null = null;
+let warnedNoHostId = false;
+const inflight = new Set<Promise<void>>();
+
+/** main.ts: the host id that names `host`-scope parameters. */
+export function configureEngineAccountStore(opts: { hostId: string | null }): void {
+  storeHostId = opts.hostId;
+}
+
+/** Tests: wait for every queued mirror/delete to settle. */
+export async function settleEngineAccountStoreWrites(): Promise<void> {
+  while (inflight.size > 0) await Promise.allSettled([...inflight]);
+}
+
+/**
+ * The parameter a row mirrors to: `<prefix>/orgs/<orgId>/engines/<kind>/<id>`
+ * for a workspace's account, `<prefix>/hosts/<hostId>/engines/<kind>/<id>` for
+ * the host's own. Null when a host-scope row has no host id to file under.
+ * Throws when an id would not be a legal path segment.
+ */
+export function engineAccountParameterName(
+  row: { id: string; kind: string; scope?: string | null },
+  hostId: string | null = storeHostId,
+): string | null {
+  const scope = row.scope ?? HOST_ACCOUNT_SCOPE;
+  const prefix = credentialStorePrefix();
+  if (scope === HOST_ACCOUNT_SCOPE) {
+    if (!hostId) return null;
+    return parameterName(prefix, "hosts", hostId, "engines", row.kind, row.id);
+  }
+  if (!isEngineAccountScope(scope)) throw new Error(`invalid account scope: ${scope}`);
+  return parameterName(prefix, "orgs", scope.slice("org:".length), "engines", row.kind, row.id);
+}
+
+/** Inverse of `engineAccountParameterName`; null for parameters that are not
+ *  engine accounts (future slices file MCP/GitHub credentials nearby). */
+export function parseEngineAccountParameterName(
+  name: string,
+  prefix: string = credentialStorePrefix(),
+): { scope: string; hostId?: string; kind: string; id: string } | null {
+  if (!name.startsWith(`${prefix}/`)) return null;
+  const parts = name.slice(prefix.length + 1).split("/");
+  if (parts.length !== 5 || parts[2] !== "engines") return null;
+  if (!parts.every((p) => isParameterPathSegment(p))) return null;
+  const [kindOfOwner, owner, , kind, id] = parts as [string, string, string, string, string];
+  if (kindOfOwner === "orgs") return { scope: `org:${owner}`, kind, id };
+  if (kindOfOwner === "hosts") return { scope: HOST_ACCOUNT_SCOPE, hostId: owner, kind, id };
+  return null;
+}
+
+function storedAccountFromRow(row: StoreRow): StoredEngineAccount {
+  const base = {
+    v: 1 as const,
+    id: row.id,
+    kind: row.kind,
+    label: row.label,
+    scope: row.scope ?? HOST_ACCOUNT_SCOPE,
+    position: row.position ?? 0,
+    createdAt: row.createdAt,
+  };
+  if (row.authKind === "env") {
+    const env = row.secretEnc
+      ? (JSON.parse(unpackSecret(row.secretEnc)) as Record<string, string>)
+      : {};
+    return { ...base, authKind: "env", env };
+  }
+  if (row.authKind !== "config-dir" || !row.configDir) {
+    throw new Error(`account ${row.id} has no mirrorable material`);
+  }
+  const files: Record<string, string> = {};
+  for (const entry of readdirSync(row.configDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const content = readFileSync(join(row.configDir, entry.name));
+    if (content.byteLength > MAX_STORED_FILE_BYTES) continue;
+    files[entry.name] = content.toString("utf8");
+  }
+  return { ...base, authKind: "config-dir", files };
+}
+
+function parseStoredAccount(value: string): StoredEngineAccount {
+  const parsed: unknown = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("not an object");
+  }
+  const o = parsed as Record<string, unknown>;
+  if (o.v !== 1) throw new Error(`unsupported version ${String(o.v)}`);
+  if (typeof o.id !== "string" || !isParameterPathSegment(o.id)) throw new Error("bad id");
+  if (typeof o.kind !== "string" || !isParameterPathSegment(o.kind)) throw new Error("bad kind");
+  if (typeof o.label !== "string" || !isEngineAccountLabel(o.label)) throw new Error("bad label");
+  if (typeof o.scope !== "string" || !isEngineAccountScope(o.scope)) throw new Error("bad scope");
+  if (o.authKind !== "env" && o.authKind !== "config-dir") throw new Error("bad authKind");
+  const stringMap = (v: unknown): Record<string, string> | undefined => {
+    if (v === undefined) return undefined;
+    if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error("bad map");
+    const out: Record<string, string> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      if (typeof val !== "string") throw new Error("bad map value");
+      out[k] = val;
+    }
+    return out;
+  };
+  return {
+    v: 1,
+    id: o.id,
+    kind: o.kind,
+    label: o.label,
+    authKind: o.authKind,
+    scope: o.scope,
+    position: typeof o.position === "number" ? o.position : 0,
+    createdAt: typeof o.createdAt === "number" ? o.createdAt : Date.now(),
+    env: stringMap(o.env),
+    files: stringMap(o.files),
+  };
+}
+
+function queueStoreWrite(what: string, work: (store: CredentialStore) => Promise<void>): void {
+  const store = configuredCredentialStore();
+  if (!store) return;
+  const p: Promise<void> = work(store)
+    .catch((err: unknown) => {
+      console.warn(
+        `[engine-accounts] credential store ${what} failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    })
+    .finally(() => {
+      inflight.delete(p);
+    });
+  inflight.add(p);
+}
+
+function selectRow(id: string): StoreRow | undefined {
+  return getDb()
+    .select()
+    .from(schema.engineAccounts)
+    .where(eq(schema.engineAccounts.id, id))
+    .get() as StoreRow | undefined;
+}
+
+function setStoreRef(id: string, storeRef: string): void {
+  getDb()
+    .update(schema.engineAccounts)
+    .set({ storeRef })
+    .where(eq(schema.engineAccounts.id, id))
+    .run();
+}
+
+async function putRow(store: CredentialStore, row: StoreRow, hostId: string | null): Promise<boolean> {
+  const name = engineAccountParameterName(row, hostId);
+  if (!name) {
+    if (!warnedNoHostId) {
+      warnedNoHostId = true;
+      console.warn(
+        "[engine-accounts] host-scope accounts are not mirrored until the host id is known",
+      );
+    }
+    return false;
+  }
+  await store.put(name, JSON.stringify(storedAccountFromRow(row)));
+  if (row.storeRef !== name) setStoreRef(row.id, name);
+  return true;
+}
+
+/** Mirror one row to its parameter, asynchronously and best effort. A no-op
+ *  on owned hosts. Rows read the CURRENT state when the write runs, so a
+ *  burst of edits collapses to the latest content. */
+export function mirrorEngineAccount(id: string): void {
+  queueStoreWrite(`mirror ${id}`, async (store) => {
+    const row = selectRow(id);
+    if (!row) return;
+    await putRow(store, row, storeHostId);
+  });
+}
+
+function importStoredAccount(
+  stored: StoredEngineAccount,
+  storeRef: string,
+  s: AccountSeams,
+): void {
+  const d = KINDS[stored.kind];
+  if (!d) throw new Error(`unknown engine kind ${stored.kind}`);
+  let secretEnc: string | null = null;
+  let configDir: string | null = null;
+  if (stored.authKind === "env") {
+    secretEnc = packSecret(JSON.stringify(stored.env ?? {}));
+  } else {
+    if (!d.extraHostDir) throw new Error(`${stored.kind} has no config-dir layout`);
+    const hostDir = d.extraHostDir(s.ownerHome(), stored.id);
+    mkdirSync(hostDir, { recursive: true, mode: 0o700 });
+    for (const [basename, content] of Object.entries(stored.files ?? {})) {
+      if (basename.includes("/") || basename.includes("\\") || basename === "..") {
+        throw new Error("bad file name");
+      }
+      const file = join(hostDir, basename);
+      writeFileSync(file, content, { mode: 0o600 });
+      try {
+        chmodSync(file, 0o600);
+      } catch {
+        /* best effort */
+      }
+    }
+    configDir = hostDir;
+  }
+  getDb()
+    .insert(schema.engineAccounts)
+    .values({
+      id: stored.id,
+      kind: stored.kind,
+      label: stored.label,
+      authKind: stored.authKind,
+      secretEnc,
+      configDir,
+      scope: stored.scope,
+      position: stored.position,
+      storeRef,
+      createdAt: stored.createdAt,
+    })
+    .run();
+}
+
+export interface ReconcileEngineAccountsResult {
+  /** No store is configured (an owned host); nothing was touched. */
+  skipped: boolean;
+  imported: number;
+  uploaded: number;
+  removed: number;
+  errors: number;
+}
+
+/**
+ * Host start: make the local cache agree with the store.
+ *  - a parameter with no local row is imported (a replacement host inherits
+ *    every workspace's accounts);
+ *  - a local row with no `store_ref` is uploaded (first start with the flag);
+ *  - a local row whose `store_ref` is under a successfully listed path but
+ *    absent from it was removed elsewhere — it goes locally too.
+ * Listing failures leave the rows under that path untouched.
+ */
+export async function reconcileEngineAccountsFromStore(
+  opts: { hostId?: string | null; seams?: Partial<AccountSeams> } = {},
+): Promise<ReconcileEngineAccountsResult> {
+  const result: ReconcileEngineAccountsResult = {
+    skipped: false,
+    imported: 0,
+    uploaded: 0,
+    removed: 0,
+    errors: 0,
+  };
+  const store = configuredCredentialStore();
+  if (!store) return { ...result, skipped: true };
+  const s = withDefaults(opts.seams ?? {});
+  const hostId = opts.hostId === undefined ? storeHostId : opts.hostId;
+  const prefix = credentialStorePrefix();
+  const warn = (line: string): void => console.warn(`[engine-accounts] credential store: ${line}`);
+
+  const paths = [`${prefix}/orgs`];
+  if (hostId && isParameterPathSegment(hostId)) paths.push(`${prefix}/hosts/${hostId}`);
+  const listed: Array<{ name: string; value: string }> = [];
+  const listedPrefixes: string[] = [];
+  for (const path of paths) {
+    try {
+      listed.push(...(await store.list(path)));
+      listedPrefixes.push(`${path}/`);
+    } catch (err) {
+      result.errors++;
+      warn(`listing ${path} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  const rows = getDb().select().from(schema.engineAccounts).all() as StoreRow[];
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  const seen = new Set<string>();
+  for (const param of listed) {
+    const at = parseEngineAccountParameterName(param.name, prefix);
+    if (!at) continue; // not an engine account
+    if (at.scope === HOST_ACCOUNT_SCOPE && at.hostId !== hostId) continue;
+    seen.add(param.name);
+    let stored: StoredEngineAccount;
+    try {
+      stored = parseStoredAccount(param.value);
+    } catch (err) {
+      result.errors++;
+      warn(`${param.name} is unreadable: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    if (stored.id !== at.id || stored.kind !== at.kind || stored.scope !== at.scope) {
+      result.errors++;
+      warn(`${param.name} does not describe the account its path names; ignored`);
+      continue;
+    }
+    const local = byId.get(stored.id);
+    if (local) {
+      if (local.storeRef !== param.name) setStoreRef(local.id, param.name);
+      continue;
+    }
+    try {
+      importStoredAccount(stored, param.name, s);
+      result.imported++;
+    } catch (err) {
+      result.errors++;
+      warn(`importing ${param.name} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  for (const row of rows) {
+    if (row.storeRef) {
+      const under = listedPrefixes.some((p) => row.storeRef!.startsWith(p));
+      if (under && !seen.has(row.storeRef)) {
+        removeLocalAccountRow(row);
+        result.removed++;
+      }
+      continue;
+    }
+    try {
+      if (await putRow(store, row, hostId)) result.uploaded++;
+    } catch (err) {
+      result.errors++;
+      warn(`uploading ${row.kind}/${row.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return result;
+}

package/lib/env.ts

@@ -41,6 +41,19 @@ const schema = z.object({
   // off entirely — zero telemetry bytes leave the machine.
   UAI_SENTRY_DSN: z.string().min(1).optional(),
   UAI_TELEMETRY_DISABLED: z.string().optional(),
+  // ADR-134 credential store. ONLY Uai-operated hosts set `aws-ssm`: engine
+  // accounts are then mirrored to AWS Parameter Store (SecureString, KMS) and
+  // reconciled at start. Owned hosts keep `local` — credentials never leave
+  // the machine. See docs/credential-store.md.
+  UAI_CREDENTIAL_STORE: z.enum(["local", "aws-ssm"]).default("local"),
+  UAI_CREDENTIAL_STORE_PREFIX: z
+    .string()
+    .regex(/^\/[A-Za-z0-9_.\-]+(?:\/[A-Za-z0-9_.\-]+)*$/)
+    .default("/uai"),
+  UAI_CREDENTIAL_STORE_KMS_KEY: z.string().min(1).default("alias/uai-credentials"),
+  // Shared with the ADR-121 machine provider (read raw there); the store
+  // needs it too, so surface it here for one validated read.
+  UAI_AWS_REGION: z.string().min(1).optional(),
   NODE_ENV: z
     .enum(["development", "production", "test"])
     .default("development"),

package/package.json

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

package/src/main.ts

@@ -152,8 +152,10 @@ import {
   type HostConfigResult,
 } from "../lib/host-config";
 import {
+  configureEngineAccountStore,
   hasStoredEngineAccounts,
   listEngineAccountsAllScopes,
+  reconcileEngineAccountsFromStore,
 } from "../lib/engine-accounts";
 import { createEngineConnectManager } from "../lib/engine-connect";
 import { createEngineLoginManager } from "../lib/engine-login";
@@ -440,6 +442,22 @@ try {
   );
 }
 migrateHostDb();
+// ADR-134: on a Uai-operated host the engine-account rows are a cache of the
+// credential store. Import what this host lacks and upload what was never
+// mirrored, off the startup path — task-up resolves locally either way.
+configureEngineAccountStore({ hostId });
+void reconcileEngineAccountsFromStore({ hostId })
+  .then((r) => {
+    if (r.skipped) return;
+    console.log(
+      `[engine-accounts] credential store reconciled: ${r.imported} imported, ${r.uploaded} uploaded, ${r.removed} removed, ${r.errors} errors`,
+    );
+  })
+  .catch((error: unknown) => {
+    console.warn(
+      `[engine-accounts] credential store reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  });
 // Reconcile a durable retention-off setting before recovery/connect can make
 // crash-left owner-facing terminal history observable again. Correctness
 // tombstones remain intact inside applyTerminalHistoryRetention.