@openpalm/lib 0.9.8 → 0.10.1

package/src/control-plane/config-persistence.ts

@@ -0,0 +1,270 @@
+/**
+ * Runtime file resolution and persistence for the OpenPalm control plane.
+ *
+ * Writes and derives live runtime files (compose, env, schemas).
+ * Files are validated in-place before writing; rollback is handled by
+ * the rollback module (snapshot to ~/.cache/openpalm/rollback/).
+ */
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
+import { parseEnvFile, mergeEnvContent } from './env.js';
+import type { ControlPlaneState, ArtifactMeta } from "./types.js";
+import { isChannelAddon } from "./channels.js";
+import { readStackSpec } from "./stack-spec.js";
+import { writeCapabilityVars } from "./spec-to-env.js";
+import { listEnabledAddonIds } from "./registry.js";
+
+import { generateRedactSchema } from "./redact-schema.js";
+import { readStackEnv } from "./secrets.js";
+import {
+  readCoreCompose,
+  ensureUserEnvSchema,
+  ensureSystemEnvSchema,
+} from "./core-assets.js";
+export { sha256, randomHex } from "./crypto.js";
+import { sha256, randomHex } from "./crypto.js";
+
+const DEFAULT_IMAGE_TAG = process.env.OP_IMAGE_TAG ?? "latest";
+
+// ── Stack Config (stack.yml) ─────────────────────────────────────
+
+/**
+ * Check whether Ollama is enabled via active stack/addons/ overlay.
+ */
+export function isOllamaEnabled(state: ControlPlaneState): boolean {
+  return listEnabledAddonIds(state.homeDir).includes("ollama");
+}
+
+/**
+ * Check whether admin is enabled via active stack/addons/ overlay.
+ */
+export function isAdminEnabled(state: ControlPlaneState): boolean {
+  return listEnabledAddonIds(state.homeDir).includes("admin");
+}
+
+// ── Env File Management ──────────────────────────────────────────────
+
+/**
+ * Return the env files used for docker compose --env-file args.
+ * These are the live vault env files.
+ *
+ * Order: stack.env -> user.env -> guardian.env
+ */
+export function buildEnvFiles(state: ControlPlaneState): string[] {
+  return [
+    `${state.vaultDir}/stack/stack.env`,
+    `${state.vaultDir}/user/user.env`,
+    `${state.vaultDir}/stack/guardian.env`,
+  ].filter(existsSync);
+}
+
+/**
+ * Write system-managed values to vault/stack/stack.env.
+ *
+ * Channel HMAC secrets are NOT written here — they belong in guardian.env.
+ * Use writeChannelSecrets() for channel secrets.
+ */
+export function writeSystemEnv(state: ControlPlaneState): void {
+  mkdirSync(`${state.vaultDir}/stack`, { recursive: true });
+
+  const systemEnvPath = `${state.vaultDir}/stack/stack.env`;
+
+  let base = "";
+  if (existsSync(systemEnvPath)) {
+    base = readFileSync(systemEnvPath, "utf-8");
+  } else {
+    base = generateFallbackSystemEnv(state);
+  }
+
+  // Preserve existing OP_SETUP_COMPLETE=true
+  const alreadyComplete = /^OP_SETUP_COMPLETE=true$/mi.test(base);
+
+  const adminManaged: Record<string, string> = {
+    OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
+  };
+
+  const content = mergeEnvContent(base, adminManaged, {
+    sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
+  });
+
+  writeFileSync(systemEnvPath, content);
+}
+
+function generateFallbackSystemEnv(state: ControlPlaneState): string {
+  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
+  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
+
+  return [
+    "# OpenPalm — System Configuration (managed by CLI/admin)",
+    "# Auto-generated fallback.",
+    "",
+    "# ── Authentication ──────────────────────────────────────────────────",
+    `OP_ADMIN_TOKEN=\${OP_ADMIN_TOKEN}`,
+    `OP_ASSISTANT_TOKEN=\${OP_ASSISTANT_TOKEN}`,
+    "",
+    "# ── Service Auth ─────────────────────────────────────────────────────",
+    `OP_MEMORY_TOKEN=${process.env.OP_MEMORY_TOKEN ?? ""}`,
+    "OP_OPENCODE_PASSWORD=",
+    "",
+    "# ── Paths ──────────────────────────────────────────────────────────",
+    `OP_HOME=${state.homeDir}`,
+    `OP_UID=${uid}`,
+    `OP_GID=${gid}`,
+    `OP_DOCKER_SOCK=${process.env.OP_DOCKER_SOCK ?? "/var/run/docker.sock"}`,
+    "",
+    "# ── Images ──────────────────────────────────────────────────────────",
+    `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
+    `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
+    "",
+    "# ── Ports (38XX range) ──────────────────────────────────────────────",
+    `OP_ASSISTANT_PORT=3800`,
+    `OP_ADMIN_PORT=3880`,
+    `OP_ADMIN_OPENCODE_PORT=3881`,
+    `OP_MEMORY_PORT=3898`,
+    `OP_GUARDIAN_PORT=3899`,
+    ""
+  ].join("\n");
+}
+
+// ── Stack Overlay Discovery ────────────────────────────────────────────
+
+/**
+ * Discover compose overlays from the stack directory.
+ * Returns full paths: [stack/core.compose.yml, stack/addons/{name}/compose.yml].
+ */
+export function discoverStackOverlays(stackDir: string): string[] {
+  const files: string[] = [];
+
+  const coreYml = `${stackDir}/core.compose.yml`;
+  if (existsSync(coreYml)) files.push(coreYml);
+
+  const addonsDir = `${stackDir}/addons`;
+  if (existsSync(addonsDir)) {
+    const entries = readdirSync(addonsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const addonCompose = `${addonsDir}/${entry.name}/compose.yml`;
+      if (existsSync(addonCompose)) files.push(addonCompose);
+    }
+  }
+
+  return files;
+}
+
+// ── Top-Level Operations ─────────────────────────────────────────────
+
+export function resolveRuntimeFiles(): {
+  compose: string;
+} {
+  return {
+    compose: readCoreCompose(),
+  };
+}
+
+// ── Runtime File Metadata ──────────────────────────────────────────────
+
+export function buildRuntimeFileMeta(artifacts: {
+  compose: string;
+}): ArtifactMeta[] {
+  const now = new Date().toISOString();
+  return (["compose"] as const).map((name) => ({
+    name,
+    sha256: sha256(artifacts[name]),
+    generatedAt: now,
+    bytes: Buffer.byteLength(artifacts[name])
+  }));
+}
+
+// ── Channel Secrets ────────────────────────────────────────────────────
+// Channel HMAC secrets live exclusively in vault/stack/guardian.env.
+
+const CHANNEL_SECRET_RE = /^CHANNEL_([A-Z0-9_]+)_SECRET$/;
+
+/** Extract channel secrets from parsed env entries. */
+function extractChannelSecrets(parsed: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const match = key.match(CHANNEL_SECRET_RE);
+    if (match?.[1] && value) result[match[1].toLowerCase()] = value;
+  }
+  return result;
+}
+
+/**
+ * Read channel HMAC secrets from vault/stack/guardian.env.
+ */
+export function readChannelSecrets(vaultDir: string): Record<string, string> {
+  return extractChannelSecrets(parseEnvFile(`${vaultDir}/stack/guardian.env`));
+}
+
+/**
+ * Write channel HMAC secrets to vault/stack/guardian.env.
+ * Merges with existing content; does not overwrite unrelated entries.
+ */
+export function writeChannelSecrets(vaultDir: string, secrets: Record<string, string>): void {
+  const guardianPath = `${vaultDir}/stack/guardian.env`;
+  mkdirSync(`${vaultDir}/stack`, { recursive: true });
+
+  let base = "";
+  if (existsSync(guardianPath)) {
+    base = readFileSync(guardianPath, "utf-8");
+  } else {
+    base = "# Guardian channel HMAC secrets — managed by openpalm\n";
+  }
+
+  const updates: Record<string, string> = {};
+  for (const [ch, secret] of Object.entries(secrets)) {
+    updates[`CHANNEL_${ch.toUpperCase()}_SECRET`] = secret;
+  }
+
+  const content = mergeEnvContent(base, updates);
+  writeFileSync(guardianPath, content, { mode: 0o600 });
+  // Ensure correct permissions even if file already existed with wrong mode
+  chmodSync(guardianPath, 0o600);
+}
+
+// ── Persistence (direct-write to live paths) ────────────────────────
+
+export function writeRuntimeFiles(
+  state: ControlPlaneState
+): void {
+  // Write core compose to stack/
+  const stackDir = `${state.homeDir}/stack`;
+  mkdirSync(stackDir, { recursive: true });
+  writeFileSync(`${stackDir}/core.compose.yml`, state.artifacts.compose);
+
+  // Load persisted channel HMAC secrets from guardian.env,
+  // then generate new ones for new channel addons.
+  const channelSecrets = readChannelSecrets(state.vaultDir);
+  const addonStackDir = `${state.homeDir}/stack`;
+  for (const addon of listEnabledAddonIds(state.homeDir)) {
+    const composePath = `${addonStackDir}/addons/${addon}/compose.yml`;
+    if (isChannelAddon(composePath) && !channelSecrets[addon]) {
+      channelSecrets[addon] = randomHex(16);
+    }
+  }
+
+  // Write channel secrets to guardian.env (the canonical source)
+  writeChannelSecrets(state.vaultDir, channelSecrets);
+
+  // Write system.env (no channel secrets — those live in guardian.env)
+  writeSystemEnv(state);
+
+  // Ensure env schema directories exist
+  ensureUserEnvSchema();
+  ensureSystemEnvSchema();
+
+  const spec = readStackSpec(state.configDir);
+  // Write OP_CAP_* capability vars to stack.env from stack spec
+  if (spec) {
+    writeCapabilityVars(spec, state.vaultDir);
+  }
+
+  // Generate redact.env.schema from canonical mappings
+  const systemEnv = readStackEnv(state.vaultDir);
+  const redactDir = `${state.dataDir}/secrets`;
+  mkdirSync(redactDir, { recursive: true });
+  writeFileSync(`${redactDir}/redact.env.schema`, generateRedactSchema(systemEnv));
+
+  state.artifactMeta = buildRuntimeFileMeta(state.artifacts);
+}

package/src/control-plane/core-assets.ts

@@ -1,278 +1,102 @@
 /**
- * Core asset management for the OpenPalm control plane.
+ * Core runtime asset management for the OpenPalm control plane.
  *
- * Manages DATA_HOME source-of-truth files: Caddyfile and docker-compose.yml.
- * All asset content is provided by a CoreAssetProvider (injected), not by
- * Vite $assets imports — making this module portable across Bun/Node/Vite.
+ * Manages source-of-truth files for the ~/.openpalm/ layout:
+ *   stack/              — compose runtime assets (core.compose.yml)
+ *   vault/              — env schemas
+ *
+ * This module manages runtime-owned core files only.
+ * Registry catalog refresh is handled separately in registry.ts.
+ * All ensure* functions verify that the expected files exist at OP_HOME.
+ * They create directories as needed but do NOT write file content — that
+ * is the responsibility of `refreshCoreAssets()` (GitHub download) or
+ * the CLI install command (which downloads assets before calling setup).
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync, renameSync } from "node:fs";
-import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { resolveDataHome } from "./paths.js";
+import { resolveDataDir, resolveVaultDir, resolveOpenPalmHome, resolveBackupsDir } from "./home.js";
 import { createLogger } from "../logger.js";
-import type { CoreAssetProvider } from "./core-asset-provider.js";
+import { sha256 } from "./crypto.js";
 
 const logger = createLogger("core-assets");
 
-// ── Constants ──────────────────────────────────────────────────────────
-
-const PUBLIC_ACCESS_IMPORT = "import public_access";
-const LAN_ONLY_IMPORT = "import lan_only";
-
-/** IP ranges for each access scope mode */
-const HOST_ONLY_IPS = "127.0.0.0/8 ::1";
-const LAN_IPS = "10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 127.0.0.0/8 ::1 fc00::/7 fe80::/10";
-const REMOTE_IP_LINE_RE = /@denied not remote_ip [^\n]+/;
-
-// Re-export for use by staging.ts Caddyfile staging
-export { PUBLIC_ACCESS_IMPORT, LAN_ONLY_IMPORT };
-
-/** SHA-256 hex digest of a string. */
-function sha256(content: string): string {
-  return createHash("sha256").update(content).digest("hex");
-}
+// ── Env Schema Files (vault/) ────────────────────────────────────────
 
 /**
- * Write content to a file if it has changed, backing up the old version.
+ * Ensure the user env schema directory exists and return the expected
+ * schema file path. The file itself may not exist yet — it is written
+ * by refreshCoreAssets() or the CLI install command.
  */
-function writeIfChanged(path: string, content: string): void {
-  if (!existsSync(path)) {
-    writeFileSync(path, content);
-    return;
-  }
-  const existing = readFileSync(path, "utf-8");
-  if (sha256(existing) === sha256(content)) return;
-
-  const backupDir = join(dirname(path), "backups");
-  mkdirSync(backupDir, { recursive: true });
-  const ts = new Date().toISOString().replace(/[:.]/g, "-");
-  const basename = path.split("/").pop()!;
-  copyFileSync(path, join(backupDir, `${basename}.${ts}`));
-  writeFileSync(path, content);
-}
-
-// ── Core Caddyfile (DATA_HOME source of truth) ─────────────────────────
-
-function coreCaddyfilePath(): string {
-  return `${resolveDataHome()}/caddy/Caddyfile`;
+export function ensureUserEnvSchema(): string {
+  const vaultDir = resolveVaultDir();
+  const dir = `${vaultDir}/user`;
+  mkdirSync(dir, { recursive: true });
+  const path = `${dir}/user.env.schema`;
+  return path;
 }
 
 /**
- * Ensure the system-managed core Caddyfile exists in DATA_HOME.
- * Seeds the bundled asset on first run. On subsequent runs, leaves the
- * existing file intact (user may have customized access scope).
+ * Ensure the system env schema directory exists and return the expected
+ * schema file path. The file itself may not exist yet — it is written
+ * by refreshCoreAssets() or the CLI install command.
  */
-export function ensureCoreCaddyfile(assets: CoreAssetProvider): string {
-  const path = coreCaddyfilePath();
-  mkdirSync(dirname(path), { recursive: true });
-  if (!existsSync(path)) {
-    writeFileSync(path, assets.caddyfile());
-  }
-  return path;
-}
-
-export function readCoreCaddyfile(assets: CoreAssetProvider): string {
-  const path = ensureCoreCaddyfile(assets);
-  return readFileSync(path, "utf-8");
-}
-
-// ── Env Schema Files (DATA_HOME root) ────────────────────────────────
-
-export function ensureSecretsSchema(assets: CoreAssetProvider): string {
-  const path = `${resolveDataHome()}/secrets.env.schema`;
-  if (!existsSync(path)) {
-    writeFileSync(path, assets.secretsSchema());
-  }
-  return path;
-}
-
-export function ensureStackSchema(assets: CoreAssetProvider): string {
-  const path = `${resolveDataHome()}/stack.env.schema`;
-  if (!existsSync(path)) {
-    writeFileSync(path, assets.stackSchema());
-  }
+export function ensureSystemEnvSchema(): string {
+  const vaultDir = resolveVaultDir();
+  const dir = `${vaultDir}/stack`;
+  mkdirSync(dir, { recursive: true });
+  const path = `${dir}/stack.env.schema`;
   return path;
 }
 
-export function detectAccessScope(rawCaddyfile: string): "host" | "lan" | "custom" {
-  const match = rawCaddyfile.match(REMOTE_IP_LINE_RE);
-  if (!match) return "custom";
-  const ips = match[0].replace("@denied not remote_ip", "").trim();
-  if (ips === HOST_ONLY_IPS) return "host";
-  if (ips === LAN_IPS) return "lan";
-  return "custom";
-}
-
-export function setCoreCaddyAccessScope(
-  scope: "host" | "lan",
-  assets: CoreAssetProvider
-): { ok: true } | { ok: false; error: string } {
-  const path = ensureCoreCaddyfile(assets);
-  const raw = readFileSync(path, "utf-8");
-  if (!REMOTE_IP_LINE_RE.test(raw)) {
-    return { ok: false, error: "core Caddyfile missing '@denied not remote_ip' line" };
-  }
-  const ips = scope === "host" ? HOST_ONLY_IPS : LAN_IPS;
-  const updated = raw.replace(REMOTE_IP_LINE_RE, `@denied not remote_ip ${ips}`);
-  writeFileSync(path, updated);
-  return { ok: true };
-}
-
-// ── Memory data directory (DATA_HOME) ────────────────────────────────────
-
-export function ensureMemoryDir(): string {
-  const dataHome = resolveDataHome();
-  const dir = `${dataHome}/memory`;
-  const legacyDir = `${dataHome}/openmemory`;
-
-  if (!existsSync(dir) && existsSync(legacyDir)) {
-    try {
-      renameSync(legacyDir, dir);
-    } catch (error) {
-      const code = error instanceof Error && "code" in error ? String(error.code) : "unknown";
-      const message = error instanceof Error ? error.message : String(error);
-      logger.warn("failed to migrate legacy memory dir", { legacyDir, dir, code, message });
-    }
-  }
+// ── Memory data directory ────────────────────────────────────────────
 
+export function ensureMemoryDir(dataDir?: string): string {
+  const resolved = dataDir ?? resolveDataDir();
+  const dir = `${resolved}/memory`;
   mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-// ── Core Compose (DATA_HOME source of truth) ──────────────────────────
+// ── Core Compose (stack/) ─────────────────────────────────────────────
 
 function coreComposePath(): string {
-  return `${resolveDataHome()}/docker-compose.yml`;
+  return `${resolveOpenPalmHome()}/stack/core.compose.yml`;
 }
 
-export function ensureCoreCompose(assets: CoreAssetProvider): string {
+export function ensureCoreCompose(): string {
   const path = coreComposePath();
-  const content = assets.coreCompose();
-  mkdirSync(dirname(path), { recursive: true });
-  if (!existsSync(path)) {
-    writeFileSync(path, content);
-  } else if (sha256(readFileSync(path, "utf-8")) !== sha256(content)) {
-    const backupDir = join(dirname(path), "backups");
-    mkdirSync(backupDir, { recursive: true });
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    copyFileSync(path, join(backupDir, `docker-compose.${ts}.yml`));
-    writeFileSync(path, content);
-  }
-  return path;
-}
-
-export function readCoreCompose(assets: CoreAssetProvider): string {
-  const path = ensureCoreCompose(assets);
-  return readFileSync(path, "utf-8");
-}
-
-// ── Ollama Compose Overlay (DATA_HOME source of truth) ──────────────
-
-function ollamaComposePath(): string {
-  return `${resolveDataHome()}/ollama.yml`;
-}
-
-export function ensureOllamaCompose(assets: CoreAssetProvider): string {
-  const path = ollamaComposePath();
-  const content = assets.ollamaCompose();
-  mkdirSync(dirname(path), { recursive: true });
-  if (!existsSync(path)) {
-    writeFileSync(path, content);
-  } else if (sha256(readFileSync(path, "utf-8")) !== sha256(content)) {
-    const backupDir = join(dirname(path), "backups");
-    mkdirSync(backupDir, { recursive: true });
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    copyFileSync(path, join(backupDir, `ollama.${ts}.yml`));
-    writeFileSync(path, content);
-  }
-  return path;
-}
-
-export function readOllamaCompose(assets: CoreAssetProvider): string {
-  const path = ensureOllamaCompose(assets);
-  return readFileSync(path, "utf-8");
-}
-
-// ── Admin Compose Overlay (DATA_HOME source of truth) ────────────────
-
-function adminComposePath(): string {
-  return `${resolveDataHome()}/admin.yml`;
-}
-
-export function ensureAdminCompose(assets: CoreAssetProvider): string {
-  const path = adminComposePath();
-  const content = assets.adminCompose();
   mkdirSync(dirname(path), { recursive: true });
-  if (!existsSync(path)) {
-    writeFileSync(path, content);
-  } else if (sha256(readFileSync(path, "utf-8")) !== sha256(content)) {
-    const backupDir = join(dirname(path), "backups");
-    mkdirSync(backupDir, { recursive: true });
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    copyFileSync(path, join(backupDir, `admin.${ts}.yml`));
-    writeFileSync(path, content);
-  }
   return path;
 }
 
-export function readAdminCompose(assets: CoreAssetProvider): string {
-  const path = ensureAdminCompose(assets);
+export function readCoreCompose(): string {
+  const path = coreComposePath();
   return readFileSync(path, "utf-8");
 }
 
-// ── OpenCode System Config (DATA_HOME source of truth) ──────────────
-
-export function ensureOpenCodeSystemConfig(assets: CoreAssetProvider): void {
-  const dir = `${resolveDataHome()}/assistant`;
-  mkdirSync(dir, { recursive: true });
-  writeIfChanged(`${dir}/opencode.jsonc`, assets.opencodeConfig());
-  writeIfChanged(`${dir}/AGENTS.md`, assets.agentsMd());
-}
-
-export function ensureAdminOpenCodeConfig(assets: CoreAssetProvider): void {
-  const dir = `${resolveDataHome()}/admin`;
-  mkdirSync(dir, { recursive: true });
-  writeIfChanged(`${dir}/opencode.jsonc`, assets.adminOpencodeConfig());
-  writeIfChanged(`${dir}/AGENTS.md`, assets.agentsMd());
-}
-
-// ── Core Automations (DATA_HOME source of truth) ────────────────────
+// ── OpenCode System Config ──────────────────────────────────────────
 
-export function ensureCoreAutomations(assets: CoreAssetProvider): void {
-  const dir = `${resolveDataHome()}/automations`;
+export function ensureOpenCodeSystemConfig(): void {
+  const dir = `${resolveDataDir()}/assistant`;
   mkdirSync(dir, { recursive: true });
-
-  const coreAutomations = [
-    { filename: "cleanup-logs.yml", content: assets.cleanupLogs() },
-    { filename: "cleanup-data.yml", content: assets.cleanupData() },
-    { filename: "validate-config.yml", content: assets.validateConfig() },
-  ];
-
-  for (const { filename, content } of coreAutomations) {
-    writeIfChanged(join(dir, filename), content);
-  }
 }
 
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
-const VERSION = process.env.OPENPALM_ASSET_VERSION ?? "main";
-
-const MANAGED_ASSETS: { dataRelPath: string; githubFilename: string }[] = [
-  { dataRelPath: "docker-compose.yml", githubFilename: "docker-compose.yml" },
-  { dataRelPath: "caddy/Caddyfile", githubFilename: "Caddyfile" },
-  { dataRelPath: "assistant/opencode.jsonc", githubFilename: "opencode.jsonc" },
-  { dataRelPath: "admin/opencode.jsonc", githubFilename: "admin-opencode.jsonc" },
-  { dataRelPath: "assistant/AGENTS.md", githubFilename: "AGENTS.md" },
-  { dataRelPath: "ollama.yml", githubFilename: "ollama.yml" },
-  { dataRelPath: "admin.yml", githubFilename: "admin.yml" },
-  { dataRelPath: "secrets.env.schema", githubFilename: "secrets.env.schema" },
-  { dataRelPath: "stack.env.schema", githubFilename: "stack.env.schema" }
+const VERSION = process.env.OP_ASSET_VERSION ?? "main";
+
+const MANAGED_ASSETS: { relPath: string; githubFilename: string }[] = [
+  { relPath: "stack/core.compose.yml", githubFilename: ".openpalm/stack/core.compose.yml" },
+  { relPath: "data/assistant/opencode.jsonc", githubFilename: "core/assistant/opencode/opencode.jsonc" },
+  { relPath: "data/assistant/AGENTS.md", githubFilename: "core/assistant/opencode/AGENTS.md" },
+  { relPath: "vault/user/user.env.schema", githubFilename: ".openpalm/vault/user/user.env.schema" },
+  { relPath: "vault/stack/stack.env.schema", githubFilename: ".openpalm/vault/stack/stack.env.schema" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {
   const releaseUrl = `https://github.com/${REPO}/releases/download/${VERSION}/${filename}`;
-  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${VERSION}/assets/${filename}`;
+  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${VERSION}/${filename}`;
 
   for (const url of [releaseUrl, rawUrl]) {
     try {
@@ -289,13 +113,13 @@ export async function refreshCoreAssets(): Promise<{
   backupDir: string | null;
   updated: string[];
 }> {
-  const dataHome = resolveDataHome();
+  const homeDir = resolveOpenPalmHome();
   const updated: string[] = [];
   let backupDir: string | null = null;
 
   for (const asset of MANAGED_ASSETS) {
     const freshContent = await downloadAsset(asset.githubFilename);
-    const targetPath = join(dataHome, asset.dataRelPath);
+    const targetPath = join(homeDir, asset.relPath);
 
     if (existsSync(targetPath)) {
       const currentContent = readFileSync(targetPath, "utf-8");
@@ -304,16 +128,16 @@ export async function refreshCoreAssets(): Promise<{
       }
 
       if (!backupDir) {
-        backupDir = join(dataHome, "backups", new Date().toISOString().replace(/[:.]/g, "-"));
+        backupDir = join(resolveBackupsDir(), new Date().toISOString().replace(/[:.]/g, "-"));
       }
-      const backupPath = join(backupDir, asset.dataRelPath);
+      const backupPath = join(backupDir, asset.relPath);
       mkdirSync(dirname(backupPath), { recursive: true });
       copyFileSync(targetPath, backupPath);
     }
 
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, freshContent);
-    updated.push(asset.dataRelPath);
+    updated.push(asset.relPath);
   }
 
   return { backupDir, updated };

package/src/control-plane/crypto.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared cryptographic utilities for the control plane.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+/** SHA-256 hex digest of a string. */
+export function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/** Generate a hex string using Node's crypto.randomBytes (CSPRNG). */
+export function randomHex(bytes: number): string {
+  return randomBytes(bytes).toString("hex");
+}