@openpalm/lib 0.11.0-beta.9 → 0.11.0-rc.18

package/src/index.ts

@@ -10,6 +10,7 @@
 export {
   LLM_PROVIDERS,
   EMBEDDING_DIMS,
+  PROVIDER_KEY_MAP,
   lookupEmbeddingDims,
 } from "./provider-constants.js";
 
@@ -38,6 +39,15 @@ export {
   backupOpenPalmHome,
 } from "./control-plane/backup.js";
 
+// ── Layout migration harness ────────────────────────────────────────────────
+export {
+  ensureMigrated,
+  MigrationError,
+  CURRENT_LAYOUT_VERSION,
+  LAYOUT_VERSION_KEY,
+} from "./control-plane/migrations.js";
+export type { MigrationReport } from "./control-plane/migrations.js";
+
 // ── Registry Catalog ─────────────────────────────────────────────────────
 export type {
   AddonMutationResult,
@@ -75,8 +85,7 @@ export {
   resolveConfigDir,
   resolveStashDir,
   resolveWorkspaceDir,
-  resolveCacheDir,
-  resolveStateDir,
+  resolveDataDir,
   resolveStackDir,
   resolveLogsDir,
   ensureHomeDirs,
@@ -109,12 +118,51 @@ export {
   updateSecretsEnv,
   writeAuthJsonProviderKeys,
   readStackEnv,
+  readStackSecretEnv,
+  readStackRuntimeEnv,
+  writeStackSecretEnv,
   patchSecretsEnvFile,
   maskSecretValue,
   ensureOpenCodeConfig,
+  assertNoSecretLikeStackEnvKeys,
 } from "./control-plane/secrets.js";
-export { migrateAuth0110 } from "./control-plane/migrate-0110.js";
-export type { MigrateAuth0110Result } from "./control-plane/migrate-0110.js";
+export {
+  resolveSecretsDir,
+  secretPath,
+  readSecret,
+  writeSecret,
+  ensureSecret,
+  removeSecret,
+  listSecretNames,
+  assertSafeSecretFilename,
+  listSecretFiles,
+  readSecretFile,
+  writeSecretFile,
+  removeSecretFile,
+} from './control-plane/secrets-files.js';
+export type { SecretFileInfo } from './control-plane/secrets-files.js';
+export {
+  assertSafeTaskFilename,
+  resolveTasksDir,
+  listTaskFiles,
+  readTaskFile,
+  writeTaskFile,
+  removeTaskFile,
+} from './control-plane/task-files.js';
+export type { TaskFileInfo } from './control-plane/task-files.js';
+export type {
+  SecretAuditIssue,
+  SecretAuditOptions,
+  SecretAuditResult,
+  SecretAuditSeverity,
+} from "./control-plane/secret-audit.js";
+export {
+  auditComposeSecrets,
+  auditFileBasedSecrets,
+  auditSecretFilesystem,
+  auditStackEnv,
+  isSecretLikeKey,
+} from "./control-plane/secret-audit.js";
 // ── Setup Status ────────────────────────────────────────────────────────
 export {
   isSetupComplete,
@@ -136,13 +184,35 @@ export {
   fetchProviderModels,
 } from "./control-plane/provider-models.js";
 
+// ── AKM host/assistant source wiring ──────────────────────────────────────
+export {
+  HOST_SOURCE_NAME,
+  addHostStashToOpenpalmConfig,
+  removeHostAkmSource,
+  importHostProfiles,
+} from "./control-plane/akm-sources.js";
+export type {
+  HostAkmSharingStatus,
+} from "./control-plane/host-akm-sharing.js";
+export {
+  enableHostAkmSharing,
+  disableHostAkmSharing,
+  getHostAkmSharingStatus,
+  ensureHostStashEnv,
+  isHostAkmAvailable,
+  hostAkmStashPath,
+  hostAkmConfigPath,
+} from "./control-plane/host-akm-sharing.js";
+
+// ── Atomic file write (shared by all control-plane writers) ───────────────
+export { writeFileAtomic } from "./control-plane/fs-atomic.js";
+
 // ── Core Assets ─────────────────────────────────────────────────────────
 export {
   ensureCoreCompose,
   readCoreCompose,
   ensureOpenCodeSystemConfig,
   refreshCoreAssets,
-  seedStashAssets,
   seedAssistantPersonaFiles,
 } from "./control-plane/core-assets.js";
 
@@ -156,8 +226,8 @@ export {
   buildRuntimeFileMeta,
   writeRuntimeFiles,
   writeSystemEnv,
-  readChannelSecrets,
-  writeChannelSecrets,
+  channelSecretName,
+  ensureChannelSecret,
   ensureComposeVolumeTargets,
 } from "./control-plane/config-persistence.js";
 
@@ -230,8 +300,15 @@ export { detectLocalProviders } from "./control-plane/model-runner.js";
 export {
   buildComposeOptions,
   buildComposeCliArgs,
+  resolveActiveProfiles,
 } from "./control-plane/compose-args.js";
 
+export {
+  addonProfileId,
+  canonicalAddonProfileSelection,
+  resolveHardwareProfileVariant,
+} from "./control-plane/profile-ids.js";
+
 // ── Compose Error Parsing ────────────────────────────────────────────────
 export type { ComposeServiceFailure } from "./control-plane/compose-errors.js";
 export {
@@ -239,16 +316,6 @@ export {
   summarizeComposeStderr,
 } from "./control-plane/compose-errors.js";
 
-// ── Stack Spec (v2) ──────────────────────────────────────────────────────
-export type {
-  StackSpec,
-} from "./control-plane/stack-spec.js";
-export {
-  STACK_SPEC_FILENAME,
-  writeStackSpec,
-  readStackSpec,
-} from "./control-plane/stack-spec.js";
-
 // ── Spec-to-Env Derivation ──────────────────────────────────────────────
 export type { VoiceVarsConfig } from "./control-plane/spec-to-env.js";
 export {
@@ -289,16 +356,19 @@ export {
   importHostOpenCode,
 } from "./control-plane/host-opencode.js";
 
-// ── AKM Vault ────────────────────────────────────────────────────────────
+// ── AKM user env (env:user) ──────────────────────────────────────────────
 export {
-  AKM_USER_VAULT_REF,
+  AKM_USER_ENV_REF,
+  AKM_ENV_KEYS,
   buildAkmEnv,
-  ensureAkmUserVault,
-  writeAkmVaultKey,
-  deleteAkmVaultKey,
-  readAkmUserVaultFile,
-  readUserVaultSync,
-} from "./control-plane/akm-vault.js";
+  assertAkmEnvComplete,
+  ensureAkmUserEnv,
+  writeUserEnvKey,
+  deleteUserEnvKey,
+  readUserEnvFile,
+  readUserEnvSync,
+  userEnvPathSync,
+} from "./control-plane/akm-user-env.js";
 
 // ── UI asset seeding and resolution ─────────────────────────────────────────
 export type { UiBuildUpdateResult } from "./control-plane/ui-assets.js";
@@ -309,5 +379,5 @@ export {
   resolveUiBuildDir,
   seedUiBuild,
   checkAndUpdateUiBuild,
-  readCurrentUiBuildVersion,
+  uiUpdateChannel,
 } from "./control-plane/ui-assets.js";

package/src/control-plane/akm-vault.test.ts

@@ -1,105 +0,0 @@
-/**
- * Tests for the akm vault helpers. The vault helpers spawn `akm vault set
- * <ref> <key>` and feed the secret VALUE on stdin (akm-cli >= 0.8.0).
- *
- * Tests gate on the akm CLI being on PATH so the suite stays green in
- * environments without akm installed.
- */
-import { describe, expect, it, beforeEach, afterEach, mock } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { execFileSync } from "node:child_process";
-import {
-  ensureAkmUserVault,
-  readAkmUserVaultFile,
-  writeAkmVaultKey,
-  deleteAkmVaultKey,
-  AKM_USER_VAULT_REF,
-} from "./akm-vault.js";
-import type { ControlPlaneState } from "./types.js";
-
-function makeState(homeDir: string): ControlPlaneState {
-  return {
-    homeDir,
-    configDir: join(homeDir, "config"),
-    stashDir: join(homeDir, "stash"),
-    workspaceDir: join(homeDir, "workspace"),
-    cacheDir: join(homeDir, "cache"),
-    stateDir: join(homeDir, "state"),
-    stackDir: join(homeDir, "stack"),
-    services: {},
-    artifacts: { compose: "" },
-    artifactMeta: [],
-  };
-}
-
-function hasAkmCli(): boolean {
-  try {
-    execFileSync("akm", ["--version"], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-const AKM_AVAILABLE = hasAkmCli();
-
-
-describe("writeAkmVaultKey", () => {
-  let homeDir: string;
-  let state: ControlPlaneState;
-
-  beforeEach(() => {
-    homeDir = mkdtempSync(join(tmpdir(), "openpalm-akm-write-"));
-    state = makeState(homeDir);
-    mkdirSync(state.stashDir, { recursive: true });
-    mkdirSync(`${state.stateDir}/cache/akm`, { recursive: true });
-  });
-
-  afterEach(() => {
-    rmSync(homeDir, { recursive: true, force: true });
-  });
-
-  it.skipIf(!AKM_AVAILABLE)("writes a key via `akm vault set` (stdin mode, no argv leak)", async () => {
-    const value = "argv-free-secret-9988";
-    const ok = await writeAkmVaultKey(state, "TOKEN", value);
-    expect(ok).toBe(true);
-
-    const vaultPath = await ensureAkmUserVault(state);
-    expect(vaultPath).not.toBeNull();
-    if (vaultPath) {
-      const stored = readAkmUserVaultFile(vaultPath);
-      expect(stored.TOKEN).toBe(value);
-    }
-  });
-
-  it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey removes a key via `akm vault unset`", async () => {
-    await writeAkmVaultKey(state, "TOKEN_A", "value-a");
-    await writeAkmVaultKey(state, "TOKEN_B", "value-b");
-
-    const ok = await deleteAkmVaultKey(state, "TOKEN_A");
-    expect(ok).toBe(true);
-
-    const vaultPath = await ensureAkmUserVault(state);
-    if (vaultPath) {
-      const stored = readAkmUserVaultFile(vaultPath);
-      expect(stored.TOKEN_A).toBeUndefined();
-      expect(stored.TOKEN_B).toBe("value-b");
-    }
-  });
-
-  it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey is idempotent on a missing key", async () => {
-    // Deleting a key that was never set should not throw — `akm vault unset`
-    // either exits 0 or emits a "not found" message we tolerate.
-    const ok = await deleteAkmVaultKey(state, "NEVER_SET_KEY");
-    expect(ok).toBe(true);
-  });
-});
-
-
-describe("AKM_USER_VAULT_REF", () => {
-  it("exports the canonical akm ref string", () => {
-    expect(AKM_USER_VAULT_REF).toBe("vault:user");
-  });
-});

package/src/control-plane/akm-vault.ts

@@ -1,311 +0,0 @@
-/// <reference types="bun-types" />
-/**
- * akm `vault:user` helpers.
- *
- * The akm-cli vault store at `${OP_HOME}/stash/vaults/user.env` is the
- * canonical home for user-managed environment secrets. The assistant
- * entrypoint sources this file directly at startup.
- *
- * `stack.env` and `guardian.env` are operator-managed and NOT mirrored
- * into akm — mirroring them would break guardian's HMAC env_file
- * hot-reload contract.
- *
- * SECURITY: every write into the akm vault is performed by spawning
- * `akm vault set <ref> <key>` with the secret VALUE delivered via stdin
- * (akm-cli >= 0.8.0). Values never appear in argv, so they cannot leak
- * through `/proc/<pid>/cmdline`. The matching delete path uses
- * `akm vault unset <ref> <key>` which is naturally argv-safe.
- *
- * Layout:
- *   stash/         — AKM_STASH_DIR: asset content (skills, vaults, knowledge, agents)
- *   state/akm/     — AKM_DATA_DIR / AKM_STATE_DIR / AKM_CONFIG_DIR: operational metadata
- *   cache/akm/     — AKM_CACHE_DIR: regenerable registry artifacts
- */
-import { existsSync, readFileSync } from "node:fs";
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
-import { parseEnvFile } from "./env.js";
-import { createLogger } from "../logger.js";
-import type { ControlPlaneState } from "./types.js";
-
-const execFile = promisify(execFileCb);
-const logger = createLogger("akm-vault");
-
-export const AKM_USER_VAULT_REF = "vault:user";
-
-/**
- * Build the env that points akm at the shared OpenPalm stash. We mirror the
- * layout that the assistant/admin containers use (see
- * `.openpalm/config/stack/core.compose.yml`) so host-side and container-side
- * runs resolve to the same vault file.
- *
- * AKM_CONFIG_DIR lives in config/ (alongside stack.env, auth.json) so
- * operators can inspect and version-control akm setup alongside other config.
- * AKM_CACHE_DIR lives in cache/ since registry index and downloaded artifacts
- * are regenerable and should not be indexed alongside stash assets.
- */
-export function buildAkmEnv(state: ControlPlaneState): NodeJS.ProcessEnv {
-  const akmOperational = `${state.stateDir}/akm`;
-  return {
-    ...process.env,
-    AKM_STASH_DIR: state.stashDir,
-    AKM_CONFIG_DIR: `${state.configDir}/akm`,
-    AKM_DATA_DIR: `${akmOperational}/data`,
-    AKM_STATE_DIR: `${akmOperational}/state`,
-    AKM_CACHE_DIR: `${state.cacheDir}/akm`,
-  };
-}
-
-/**
- * Per-invocation timeout (ms) for every akm subprocess we launch. The CLI is
- * a local binary and these probes (`--version`, `vault create`, `vault path`,
- * `vault set/unset`) complete in well under a second on a healthy host;
- * anything longer means akm is wedged or unreachable. Bounding the call
- * keeps `mirrorUserVaultToAkm` truly best-effort: a stuck akm binary cannot
- * block install/upgrade.
- *
- * Why a wall-clock race instead of execFile's built-in `timeout` option:
- * node's `child_process.execFile` in Bun is implemented on top of `Bun.spawn`,
- * and its `timeout` option only fires once stdout/stderr are wired up. Test
- * suites that stub `Bun.spawn` (e.g. `packages/cli/src/main.test.ts`
- * `mockDockerCli`) return a fake child whose stdout never closes, so neither
- * the underlying promise nor the timeout option ever resolves. A simple
- * `Promise.race` against an unref'd setTimeout converts that failure mode
- * into a fast rejection that `akmAvailable` swallows as "akm not on PATH",
- * without changing behaviour on real hosts.
- */
-const AKM_EXEC_TIMEOUT_MS = 2_000;
-
-/**
- * Race a promise against an unref'd setTimeout. If the timeout fires first,
- * reject with `<label> timed out after <ms>ms`. The timer is always cleared
- * in `finally` so it never keeps the event loop alive past resolution. The
- * unref means the timer alone won't block process exit — the surrounding
- * subprocess work owns the liveness.
- */
-function raceWithTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    timer.unref?.();
-  });
-  return Promise.race([promise, timeoutPromise]).finally(() => {
-    if (timer) clearTimeout(timer);
-  });
-}
-
-async function execAkm(args: string[], env: NodeJS.ProcessEnv): Promise<{ stdout: string; stderr: string }> {
-  return raceWithTimeout(
-    execFile("akm", args, { env }),
-    AKM_EXEC_TIMEOUT_MS,
-    `akm ${args[0] ?? "?"}`,
-  );
-}
-
-async function akmAvailable(env: NodeJS.ProcessEnv): Promise<boolean> {
-  try {
-    await execAkm(["--version"], env);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Return the absolute path of the akm vault file, creating the vault if
- * missing. Callers that have already built the akm env (via `buildAkmEnv`)
- * can pass it in to avoid rebuilding — the result is identical either way.
- */
-export async function ensureAkmUserVault(
-  state: ControlPlaneState,
-  env: NodeJS.ProcessEnv = buildAkmEnv(state),
-): Promise<string | null> {
-  if (!(await akmAvailable(env))) {
-    return null;
-  }
-  try {
-    // `vault create` accepts only the ref on argv — no secret material crosses
-    // the process boundary here.
-    await execAkm(["vault", "create", AKM_USER_VAULT_REF], env);
-  } catch (err) {
-    // `create` is documented as a no-op when the vault already exists, but
-    // some build channels emit a non-zero exit. Probe `path` to distinguish
-    // a real failure from "already exists".
-    logger.debug("akm vault create returned non-zero", {
-      ref: AKM_USER_VAULT_REF,
-      error: err instanceof Error ? err.message : String(err),
-    });
-  }
-  try {
-    const { stdout } = await execAkm(["vault", "path", AKM_USER_VAULT_REF], env);
-    const path = stdout.trim();
-    return path.length > 0 ? path : null;
-  } catch (err) {
-    logger.warn("akm vault path failed", {
-      ref: AKM_USER_VAULT_REF,
-      error: err instanceof Error ? err.message : String(err),
-    });
-    return null;
-  }
-}
-
-/**
- * Spawn `akm vault set <ref> <key>` and feed the secret VALUE via stdin.
- * The value never crosses argv, so it cannot leak through
- * `/proc/<pid>/cmdline`. Bounded by AKM_EXEC_TIMEOUT_MS — a stuck akm
- * binary cannot block the calling install/upgrade flow.
- */
-async function akmVaultSetViaStdin(
-  ref: string,
-  key: string,
-  value: string,
-  env: NodeJS.ProcessEnv,
-): Promise<void> {
-  // We use Bun.spawn directly because it supports an in-memory stdin pipe
-  // (a buffer/string stream) without dragging in an extra dependency, and
-  // because akm-cli on >= 0.8.0 reads the value from stdin when no
-  // positional `<value>` is provided. (The CLI silently switched stdin to
-  // the default in commit c50f9f4; explicit `--stdin` is still accepted
-  // for older binaries — but since we pin akm-cli >= 0.8.0-rc2 across all
-  // images via Dockerfile ARGs, the implicit form is enough.)
-  const child = Bun.spawn(["akm", "vault", "set", ref, key], {
-    env,
-    stdin: "pipe",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  // Feed the secret. `child.stdin` is a FileSink in Bun — write+end then
-  // wait for exit. We don't use `await child.stdin.end(value)` because
-  // some Bun versions return undefined here; explicit write+end is portable.
-  if (child.stdin) {
-    // child.stdin is typed as FileSink in Bun
-    const sink = child.stdin as { write: (data: string) => unknown; end: () => unknown };
-    sink.write(value);
-    sink.end();
-  }
-
-  // Wall-clock bound — mirror of the execAkm pattern. On timeout we also
-  // SIGKILL the child so the orphaned subprocess doesn't outlive us.
-  let exitCode: number;
-  try {
-    exitCode = await raceWithTimeout(
-      child.exited,
-      AKM_EXEC_TIMEOUT_MS,
-      `akm vault set ${key}`,
-    );
-  } catch (err) {
-    try { child.kill(); } catch { /* best-effort */ }
-    throw err;
-  }
-
-  if (exitCode !== 0) {
-    const stderrText = child.stderr ? await new Response(child.stderr).text() : "";
-    throw new Error(`akm vault set ${key} failed (exit ${exitCode}): ${stderrText.trim()}`);
-  }
-}
-
-/**
- * Write a single key/value into the akm `vault:user` store via
- * `akm vault set <ref> <key>` with the value delivered on stdin.
- *
- * Returns `true` on success, `false` when akm is unavailable or the vault
- * could not be ensured. Throws on akm subprocess failures (non-zero exit
- * with a captured stderr, or wall-clock timeout) so callers can surface
- * the real error instead of silently dropping the write.
- */
-export async function writeAkmVaultKey(
-  state: ControlPlaneState,
-  key: string,
-  value: string,
-): Promise<boolean> {
-  // Build env once and thread it through both the ensure step and the
-  // subsequent `akm vault set`. Avoids a redundant `buildAkmEnv` call.
-  const env = buildAkmEnv(state);
-  const vaultPath = await ensureAkmUserVault(state, env);
-  if (!vaultPath) return false;
-  await akmVaultSetViaStdin(AKM_USER_VAULT_REF, key, value, env);
-  return true;
-}
-
-/**
- * Remove a key from the akm `vault:user` store via `akm vault unset`.
- * The key name is a normal identifier and crosses argv only — secret
- * values are never involved. Returns `true` if the operation completed
- * (whether or not the key was present), `false` when akm is unavailable.
- */
-export async function deleteAkmVaultKey(
-  state: ControlPlaneState,
-  key: string,
-): Promise<boolean> {
-  // Build env once and pass it into ensureAkmUserVault so we don't pay
-  // for two `buildAkmEnv` calls on a single delete.
-  const env = buildAkmEnv(state);
-  const vaultPath = await ensureAkmUserVault(state, env);
-  if (!vaultPath) return false;
-  try {
-    // --yes: newer akm versions require explicit confirmation for any
-    // destructive operation in non-interactive mode. Without this flag
-    // the command exits with NON_INTERACTIVE_REQUIRES_YES and our
-    // delete looks like a hard failure instead of an idempotent unset.
-    await execAkm(["vault", "unset", "--yes", AKM_USER_VAULT_REF, key], env);
-  } catch (err) {
-    // `unset` of a missing key is a benign no-op; many akm versions exit 0
-    // anyway. If akm hard-fails (non-zero, non-empty stderr) we surface it.
-    const message = err instanceof Error ? err.message : String(err);
-    // Heuristic: tolerate "not found" / "no such" messages so re-running
-    // delete on an already-deleted key stays idempotent for callers.
-    if (/not\s*found|no\s+such|does\s+not\s+exist/i.test(message)) {
-      logger.debug("akm vault unset reported missing key", { key, message });
-      return true;
-    }
-    throw err;
-  }
-  return true;
-}
-
-/**
- * Synchronously resolve the canonical akm `vault:user` file path for a given
- * control-plane state. Used by sync read paths (e.g. plaintext secret backend
- * `list`/`exists`) that cannot await `ensureAkmUserVault`.
- *
- * The path is deterministic: `buildAkmEnv` pins `AKM_STASH_DIR` to
- * `state.stashDir`, and akm-cli (>= 0.8.0) materializes vault files
- * at `${AKM_STASH_DIR}/vaults/<ref>.env`.
- *
- * Returns the path string regardless of whether the file currently exists —
- * callers should `existsSync` if presence matters.
- */
-export function akmUserVaultPathSync(state: ControlPlaneState): string {
-  return `${state.stashDir}/vaults/user.env`;
-}
-
-/**
- * Read the user-managed env namespace from the akm `vault:user` store.
- *
- * Returns `{}` when the vault file does not exist yet. Pure sync — no subprocess spawn.
- */
-export function readUserVaultSync(state: ControlPlaneState): Record<string, string> {
-  const akmPath = akmUserVaultPathSync(state);
-  if (existsSync(akmPath)) {
-    return readAkmUserVaultFile(akmPath);
-  }
-  return {};
-}
-
-/** Return the parsed contents of the akm vault file (public API used by admin UI list endpoint). */
-export function readAkmUserVaultFile(vaultPath: string): Record<string, string> {
-  if (!existsSync(vaultPath)) return {};
-  try {
-    return parseEnvFile(vaultPath);
-  } catch {
-    // Fallback: hand-parse if dotenv chokes (e.g. file with stray BOM).
-    const raw = readFileSync(vaultPath, "utf-8");
-    const out: Record<string, string> = {};
-    for (const line of raw.split("\n")) {
-      const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-      if (m) out[m[1]] = m[2];
-    }
-    return out;
-  }
-}