@openpalm/lib 0.10.2 → 0.11.0-beta.10

package/src/control-plane/migrate-0110.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for the 0.11.0 auth-migration shim.
+ */
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { migrateAuth0110 } from "./migrate-0110.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, "config", "stack"),
+    services: {},
+    artifacts: { compose: "" },
+    artifactMeta: [],
+  };
+}
+
+function seedStackEnv(stackDir: string, content: string): string {
+  mkdirSync(stackDir, { recursive: true });
+  const path = join(stackDir, "stack.env");
+  writeFileSync(path, content, { encoding: "utf-8", mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+describe("migrateAuth0110", () => {
+  let homeDir: string;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "openpalm-migrate-0110-"));
+  });
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it("no-ops on a fresh install (no stack.env)", () => {
+    const state = makeState(homeDir);
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(false);
+    expect(result.reason).toContain("fresh install");
+  });
+
+  it("promotes OP_UI_TOKEN → OP_UI_LOGIN_PASSWORD and removes legacy keys", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "# header",
+        "OP_UI_TOKEN=legacy-token-value",
+        "OP_ASSISTANT_TOKEN=some-assistant-token",
+        "OP_OPENCODE_PASSWORD=opencode-secret",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).toContain("promoted OP_UI_TOKEN");
+    expect(result.reason).toContain("removed OP_UI_TOKEN");
+    expect(result.reason).toContain("removed OP_ASSISTANT_TOKEN");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    expect(after).toContain("OP_UI_LOGIN_PASSWORD=legacy-token-value");
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+    expect(after).not.toMatch(/^OP_ASSISTANT_TOKEN=/m);
+    // Unrelated keys preserved
+    expect(after).toContain("OP_OPENCODE_PASSWORD=opencode-secret");
+
+    // Perms preserved
+    expect(statSync(stackEnvPath).mode & 0o777).toBe(0o600);
+
+    // Migration log appended
+    const logPath = join(state.stateDir, "logs", "migration-0.11.0.log");
+    expect(existsSync(logPath)).toBe(true);
+    const log = readFileSync(logPath, "utf-8");
+    expect(log).toContain("migrate-auth-0110");
+    expect(log).toContain("promoted OP_UI_TOKEN");
+  });
+
+  it("does not overwrite an existing OP_UI_LOGIN_PASSWORD", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_LOGIN_PASSWORD=new-password",
+        "OP_UI_TOKEN=legacy-value",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).not.toContain("promoted");
+    expect(result.reason).toContain("removed OP_UI_TOKEN");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    expect(after).toContain("OP_UI_LOGIN_PASSWORD=new-password");
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+  });
+
+  it("removes OP_ASSISTANT_TOKEN even when only it is present", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_LOGIN_PASSWORD=pw",
+        "OP_ASSISTANT_TOKEN=stale",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).toContain("removed OP_ASSISTANT_TOKEN");
+    expect(readFileSync(stackEnvPath, "utf-8")).not.toMatch(/^OP_ASSISTANT_TOKEN=/m);
+  });
+
+  it("is idempotent: second run reports already-migrated", () => {
+    const state = makeState(homeDir);
+    seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_TOKEN=t",
+        "OP_ASSISTANT_TOKEN=t2",
+        "",
+      ].join("\n"),
+    );
+
+    const first = migrateAuth0110(state);
+    expect(first.migrated).toBe(true);
+
+    const second = migrateAuth0110(state);
+    expect(second.migrated).toBe(false);
+    expect(second.reason).toContain("already migrated");
+  });
+
+  it("treats an empty OP_UI_TOKEN value as not-set (no promotion)", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_TOKEN=",
+        "OP_ASSISTANT_TOKEN=foo",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    // Empty-string OP_UI_TOKEN should NOT be promoted as a password.
+    expect(result.reason).not.toContain("promoted");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    // The empty OP_UI_TOKEN line is still removed.
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+    // No OP_UI_LOGIN_PASSWORD added (would be an empty value).
+    expect(after).not.toMatch(/^OP_UI_LOGIN_PASSWORD=/m);
+  });
+});

package/src/control-plane/migrate-0110.ts

@@ -0,0 +1,99 @@
+/**
+ * One-shot migration for the 0.11.0 auth refactor.
+ *
+ * Existing installs have OP_UI_TOKEN and OP_ASSISTANT_TOKEN in
+ * config/stack/stack.env. The 0.11.0 refactor (auth-and-proxy-refactor-plan.md)
+ * replaces them with a single OP_UI_LOGIN_PASSWORD. If we don't migrate,
+ * operators get locked out the moment they run the new UI build because the
+ * login route compares the cookie against process.env.OP_UI_LOGIN_PASSWORD,
+ * which is empty on existing installs.
+ *
+ * Migration logic (idempotent):
+ *   - If OP_UI_LOGIN_PASSWORD is unset AND OP_UI_TOKEN is set, copy
+ *     OP_UI_TOKEN's value into OP_UI_LOGIN_PASSWORD.
+ *   - Remove OP_UI_TOKEN and OP_ASSISTANT_TOKEN from stack.env (they're
+ *     no longer used).
+ *   - Append a one-line summary to state/logs/migration-0.11.0.log.
+ *   - If OP_UI_LOGIN_PASSWORD is already set, leave it alone — the operator
+ *     already migrated or set up fresh.
+ *
+ * Called from ensureSecrets so it runs before any auth-required code path
+ * gets a chance to see the half-migrated state.
+ */
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  appendFileSync,
+  mkdirSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { parseEnvContent, removeEnvKey, upsertEnvValue } from "./env.js";
+import { migration0110LogPath } from "./paths.js";
+import type { ControlPlaneState } from "./types.js";
+
+export type MigrateAuth0110Result = {
+  /** True if any change was written to stack.env. */
+  migrated: boolean;
+  /** Human-readable description of what changed (or why nothing did). */
+  reason: string;
+};
+
+export function migrateAuth0110(state: ControlPlaneState): MigrateAuth0110Result {
+  const stackEnvPath = `${state.stackDir}/stack.env`;
+  if (!existsSync(stackEnvPath)) {
+    return { migrated: false, reason: "no stack.env yet (fresh install)" };
+  }
+
+  const before = readFileSync(stackEnvPath, "utf-8");
+  const parsed = parseEnvContent(before);
+  const hasLoginPw = typeof parsed.OP_UI_LOGIN_PASSWORD === "string" && parsed.OP_UI_LOGIN_PASSWORD.length > 0;
+  const hasUiToken = typeof parsed.OP_UI_TOKEN === "string" && parsed.OP_UI_TOKEN.length > 0;
+  const hasAssistantToken = "OP_ASSISTANT_TOKEN" in parsed;
+  const hasUiTokenLine = "OP_UI_TOKEN" in parsed;
+
+  if (hasLoginPw && !hasUiTokenLine && !hasAssistantToken) {
+    return { migrated: false, reason: "already migrated" };
+  }
+
+  let content = before;
+  const changes: string[] = [];
+
+  if (!hasLoginPw && hasUiToken) {
+    content = upsertEnvValue(content, "OP_UI_LOGIN_PASSWORD", parsed.OP_UI_TOKEN);
+    changes.push("promoted OP_UI_TOKEN → OP_UI_LOGIN_PASSWORD");
+  }
+  if (hasUiTokenLine) {
+    content = removeEnvKey(content, "OP_UI_TOKEN");
+    changes.push("removed OP_UI_TOKEN");
+  }
+  if (hasAssistantToken) {
+    content = removeEnvKey(content, "OP_ASSISTANT_TOKEN");
+    changes.push("removed OP_ASSISTANT_TOKEN");
+  }
+
+  if (changes.length === 0) {
+    return { migrated: false, reason: "no changes needed" };
+  }
+
+  // Preserve the 0600 mode the existing file should already have.
+  writeFileSync(stackEnvPath, content, { encoding: "utf-8", mode: 0o600 });
+  try { chmodSync(stackEnvPath, 0o600); } catch { /* best-effort */ }
+
+  // Best-effort audit line. The migration log is small and append-only;
+  // if it fails (perm error, fs full), we don't roll back the migration.
+  try {
+    const logPath = migration0110LogPath(state);
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(
+      logPath,
+      `${new Date().toISOString()} migrate-auth-0110 ${changes.join("; ")}\n`,
+      "utf-8",
+    );
+  } catch {
+    /* best-effort */
+  }
+
+  return { migrated: true, reason: changes.join("; ") };
+}

package/src/control-plane/operator-ids.test.ts

@@ -0,0 +1,130 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
+
+let tempDir = "";
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "openpalm-opids-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("resolveOperatorIds", () => {
+  test("returns the homeDir's owner when it exists and is non-root", () => {
+    // A mkdtemp directory is owned by the current process — neither
+    // root (in any reasonable test env) nor a hard-coded 1000.
+    const expected = statSync(tempDir);
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBe(expected.uid);
+    expect(ids!.gid).toBe(expected.gid);
+  });
+
+  test("falls back to process UID when homeDir does not exist", () => {
+    const missing = join(tempDir, "does-not-exist");
+    const ids = resolveOperatorIds(missing);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    // process.getuid is guaranteed on POSIX runtimes used by this test
+    expect(ids!.uid).toBe(process.getuid!());
+    expect(ids!.gid).toBe(process.getgid!());
+  });
+
+  test("never returns 0 (root) — falls back to process UID when homeDir is root-owned", () => {
+    // We can't easily chown a dir to root without root. Instead, exercise
+    // the branch via a faked statSync output: build a path that triggers
+    // the "owner is 0, prefer process UID" code path by ensuring real
+    // tempDir owner is the process UID and asserting the result for a
+    // missing path matches process UID (already covered above). The
+    // explicit 0-check is enforced by the implementation; this test
+    // documents that the function never *returns* 0 for any of the
+    // exercised inputs in a non-root test process.
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBeGreaterThan(0);
+    expect(ids!.gid).toBeGreaterThan(0);
+  });
+
+  test("returns null when BOTH homeDir owner and process UID/GID are 0 (root install on root-owned OP_HOME)", () => {
+    if (process.platform === "win32") {
+      // win32 short-circuits before any of this logic
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+      return;
+    }
+
+    // Stub process.getuid / getgid to simulate running as root. On Linux,
+    // `/` is owned by uid=0 gid=0, so passing "/" gives us a root-owned
+    // homeDir. Combined with the stubbed process IDs, this hits the
+    // "both signals are root" branch that previously returned {0,0}.
+    const origGetuid = process.getuid;
+    const origGetgid = process.getgid;
+    try {
+      (process as unknown as { getuid: () => number }).getuid = () => 0;
+      (process as unknown as { getgid: () => number }).getgid = () => 0;
+      // Sanity-check the assumption that "/" is root-owned in this env
+      // before relying on it as a fixture. On macOS / Linux CI runners
+      // this holds; if a future weird env breaks it, the assertion
+      // surfaces clearly rather than producing a confusing pass.
+      const rootStat = statSync("/");
+      expect(rootStat.uid).toBe(0);
+      expect(rootStat.gid).toBe(0);
+
+      const ids = resolveOperatorIds("/");
+      expect(ids).toBeNull();
+    } finally {
+      (process as unknown as { getuid: typeof origGetuid }).getuid = origGetuid;
+      (process as unknown as { getgid: typeof origGetgid }).getgid = origGetgid;
+    }
+  });
+
+  test("returns null on win32", () => {
+    // This test is informational; on non-win32 it doesn't run the win32
+    // branch. The check is left here for documentation and runs as a
+    // no-op assertion on POSIX.
+    if (process.platform === "win32") {
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+    } else {
+      // No-op: confirms the test compiles and the helper is callable.
+      expect(typeof resolveOperatorIds).toBe("function");
+    }
+  });
+});
+
+describe("hasUsableOperatorId", () => {
+  test("returns true for positive numeric values", () => {
+    expect(hasUsableOperatorId({ OP_UID: "1000" }, "OP_UID")).toBe(true);
+    expect(hasUsableOperatorId({ OP_GID: "501" }, "OP_GID")).toBe(true);
+  });
+
+  test("returns false for missing key", () => {
+    expect(hasUsableOperatorId({}, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for empty string", () => {
+    expect(hasUsableOperatorId({ OP_UID: "" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for zero", () => {
+    expect(hasUsableOperatorId({ OP_UID: "0" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for non-numeric garbage", () => {
+    expect(hasUsableOperatorId({ OP_UID: "abc" }, "OP_UID")).toBe(false);
+  });
+});

package/src/control-plane/operator-ids.ts

@@ -0,0 +1,89 @@
+/**
+ * Operator UID/GID detection for stack.env.
+ *
+ * Container processes that bind-mount host paths (voice models, addon
+ * caches, etc.) run as `${OP_UID}:${OP_GID}`. If those values are wrong,
+ * the container can't write to the mounted volume and the install
+ * silently degrades (model downloads stall, healthchecks time out).
+ *
+ * Detection strategy (Linux/macOS):
+ *   1. Stat OP_HOME. If it exists and is owned by a non-root user,
+ *      prefer that owner — operator may have created OP_HOME under a
+ *      different account than the one running install (e.g. sudo
+ *      install for a service user).
+ *   2. Otherwise fall back to the process's real UID/GID.
+ *   3. Never return 0 (root). Running install as root is allowed but
+ *      the container must run as the operator, not root.
+ *
+ * Returns `null` on Windows (containers run in WSL2's Linux; OP_UID
+ * has no meaning on the win32 host process itself).
+ */
+import { statSync } from "node:fs";
+
+export type OperatorIds = { uid: number; gid: number };
+
+/**
+ * Resolve the operator's UID/GID for stack.env.
+ * Returns null on Windows or when neither homeDir owner nor process
+ * UID/GID is available (e.g. process.getuid undefined on some runtimes).
+ */
+export function resolveOperatorIds(homeDir: string): OperatorIds | null {
+  if (process.platform === "win32") return null;
+
+  const processUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const processGid = typeof process.getgid === "function" ? process.getgid() : undefined;
+
+  let ownerUid: number | undefined;
+  let ownerGid: number | undefined;
+  try {
+    const st = statSync(homeDir);
+    ownerUid = st.uid;
+    ownerGid = st.gid;
+  } catch {
+    // homeDir may not exist yet during a first-time install — that's fine,
+    // we fall through to the process IDs below.
+  }
+
+  // Prefer the homeDir owner when it's a non-root user (the operator may
+  // have created OP_HOME under a different account than the one running
+  // install — e.g. an admin running `sudo openpalm install` on behalf of
+  // a service account).
+  const uid =
+    ownerUid !== undefined && ownerUid !== 0
+      ? ownerUid
+      : processUid !== undefined && processUid !== 0
+        ? processUid
+        : ownerUid; // last resort: homeDir owner even if 0, or undefined
+
+  const gid =
+    ownerGid !== undefined && ownerGid !== 0
+      ? ownerGid
+      : processGid !== undefined && processGid !== 0
+        ? processGid
+        : ownerGid;
+
+  if (uid === undefined || gid === undefined) return null;
+
+  // Final guard: never return 0 (root). This happens when BOTH the OP_HOME
+  // owner AND the process UID are root (e.g. `sudo openpalm install` on a
+  // freshly-created root-owned OP_HOME, common in CI builds and Docker-based
+  // installer flows). Returning null causes the caller to skip writing
+  // OP_UID/OP_GID to stack.env, and compose's `${OP_UID:-1000}` default
+  // kicks in — container runs as 1000:1000, which is the sane fallback
+  // when no real operator can be detected.
+  if (uid === 0 || gid === 0) return null;
+
+  return { uid, gid };
+}
+
+/**
+ * Returns true if the parsed stack.env already has a usable
+ * (non-zero, numeric) operator ID for the given key.
+ * Operator may have hand-set OP_UID/OP_GID; respect that.
+ */
+export function hasUsableOperatorId(parsed: Record<string, string>, key: "OP_UID" | "OP_GID"): boolean {
+  const raw = parsed[key];
+  if (!raw) return false;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0;
+}

package/src/control-plane/paths.ts

@@ -0,0 +1,80 @@
+/**
+ * Authoritative path resolution for the OpenPalm control plane.
+ *
+ * Every consumer imports from here instead of concatenating paths inline.
+ * When the directory layout changes, update this file only.
+ *
+ * Layout:
+ *   config/        — user-editable config + system config files (auth.json, akm/)
+ *   config/stack/  — compose runtime + stack config (stack.env, guardian.env, stack.yml, addons/)
+ *   cache/         — regenerable/semi-persistent data (akm cache, guardian cache, rollback)
+ *   state/         — persistent service data (assistant, admin, guardian, logs, backups, registry)
+ *   stash/         — akm knowledge (skills, vaults, agents)
+ *   workspace/     — shared work area
+ */
+import type { ControlPlaneState } from "./types.js";
+
+// ── Config directory — user + system config ─────────────────────────────────
+
+/** OpenCode auth token store */
+export const authJsonPath          = (s: ControlPlaneState): string => `${s.configDir}/auth.json`;
+/** akm setup config directory (AKM_CONFIG_DIR) */
+export const akmConfigDir          = (s: ControlPlaneState): string => `${s.configDir}/akm`;
+/** akm setup config file (written by admin on capability save) */
+export const akmConfigPath         = (s: ControlPlaneState): string => `${s.configDir}/akm/config.json`;
+export const tasksDir              = (s: ControlPlaneState): string => `${s.stashDir}/tasks`;
+export const assistantConfigDir    = (s: ControlPlaneState): string => `${s.configDir}/assistant`;
+
+// ── Config/stack directory — compose runtime + stack config ─────────────────
+
+/** System env: capabilities, secrets, tokens */
+export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stackDir}/stack.env`;
+/** Guardian HMAC channel secrets */
+export const guardianEnvPath       = (s: ControlPlaneState): string => `${s.stackDir}/guardian.env`;
+
+// ── Cache directory — regenerable/semi-persistent ───────────────────────────
+
+export const akmCacheDir           = (s: ControlPlaneState): string => `${s.cacheDir}/akm`;
+export const guardianCacheDir      = (s: ControlPlaneState): string => `${s.cacheDir}/guardian`;
+export const rollbackDir           = (s: ControlPlaneState): string => `${s.cacheDir}/rollback`;
+
+// ── State directory — persistent service data ───────────────────────────────
+
+export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.stateDir}/assistant`;
+export const adminServiceDir       = (s: ControlPlaneState): string => `${s.stateDir}/admin`;
+export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.stateDir}/guardian`;
+export const guardianStashDir      = (s: ControlPlaneState): string => `${s.stateDir}/guardian/stash`;
+export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.stateDir}/guardian/akm`;
+/** Shared akm operational data (data/, state/ — NOT config, which lives in config/akm/) */
+export const akmStateDir           = (s: ControlPlaneState): string => `${s.stateDir}/akm`;
+export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.cacheDir}/akm/tasks/logs/${id}`;
+export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.cacheDir}/akm/tasks/logs`;
+export const logsDir               = (s: ControlPlaneState): string => `${s.stateDir}/logs`;
+/**
+ * Guardian's own audit log of channel ingress (HMAC verify, replay, rate
+ * limit). Phase 6 of the auth/proxy refactor removed the OpenPalm-side
+ * `admin-audit.jsonl` — OpenCode session logs are the audit trail for
+ * chat + tool activity.
+ */
+export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.stateDir}/logs/guardian-audit.log`;
+/** One-shot 0.11.0 migration log (OP_UI_TOKEN → OPENCODE_SERVER_PASSWORD, endpoints.json move) */
+export const migration0110LogPath  = (s: ControlPlaneState): string => `${s.stateDir}/logs/migration-0.11.0.log`;
+export const backupsDir            = (s: ControlPlaneState): string => `${s.stateDir}/backups`;
+export const registryDir           = (s: ControlPlaneState): string => `${s.stateDir}/registry`;
+export const registryAddonsDir     = (s: ControlPlaneState): string => `${s.stateDir}/registry/addons`;
+export const registryAutomationsDir = (s: ControlPlaneState): string => `${s.stateDir}/registry/automations`;
+export const secretsDir            = (s: ControlPlaneState): string => `${s.stateDir}/secrets`;
+export const secretProviderPath    = (s: ControlPlaneState): string => `${s.stateDir}/secrets/provider.json`;
+export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.stateDir}/secrets/plaintext-index.json`;
+export const passStoreDir          = (s: ControlPlaneState): string => `${s.stateDir}/secrets/pass-store`;
+
+// ── Stash directory ─────────────────────────────────────────────────────────
+
+/** akm vault:user file — lives in the stash */
+export const akmUserVaultPath      = (s: ControlPlaneState): string => `${s.stashDir}/vaults/user.env`;
+
+// ── Stack directory ─────────────────────────────────────────────────────────
+
+export const coreComposePath       = (s: ControlPlaneState): string => `${s.stackDir}/core.compose.yml`;
+export const addonsStackDir        = (s: ControlPlaneState): string => `${s.stackDir}/addons`;
+export const addonComposePath      = (s: ControlPlaneState, name: string): string => `${s.stackDir}/addons/${name}/compose.yml`;