@openpalm/lib 0.11.0-rc.1 → 0.11.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.0-rc.1",
+  "version": "0.11.0-rc.3",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",

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

@@ -11,7 +11,7 @@
  *     (the user's personal ~/akm, bind-mounted by the host-akm.compose.yml overlay).
  *   - The personal config gains an `openpalm` source → OP_HOME/knowledge.
  *
- * VERIFIED against akm 0.8.0-rc.13:
+ * VERIFIED against akm 0.8.0 (rc.13 → stable; schema unchanged):
  *  - `SourceConfigEntrySchema` (config-schema.ts:259) accepts
  *    { type, path?, url?, name?, enabled?, writable?, primary?, options?, wikiName? }.
  *  - The indexer's `resolveSourceEntries` (search-source.ts:56) ALWAYS injects the

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

@@ -264,35 +264,135 @@ export function resolveUiBuildDir(): string {
 }
 
 /**
- * Install the UI build to OP_HOME/data/ui/.
- *
- * Copies from local packages/ui/build/ when running from source,
- * otherwise downloads ui-build.tar.gz from the GitHub release.
- * Called during install and update; always replaces existing content.
- *
- * data/ui/ is automatically included in backups because
- * backupOpenPalmHome() copies all of OP_HOME/data/.
+ * The UI ships as `@openpalm/ui` on npm — a self-contained `adapter-node`
+ * bundle (only `build/` is published; no `node_modules` is needed at runtime,
+ * because the build bundles every dependency). The desktop and host updaters
+ * fetch the registry TARBALL over plain HTTPS and verify its integrity hash;
+ * they never invoke a package manager (the Electron runtime has none). npm gives
+ * us, for free, the four things the GitHub-release path forced us to hand-roll:
+ * an independent version line, `latest`/`next` dist-tag channels (prerelease-
+ * aware — unlike `releases/latest`, which silently excludes prereleases),
+ * immutable versions, and a sha512 integrity we verify fail-closed.
+ */
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+const UI_PACKAGE   = '@openpalm/ui';
+
+interface NpmUiManifest {
+  version: string;
+  tarball: string;
+  /** Subresource-integrity string ("sha512-<base64>"); null if the registry omitted it. */
+  integrity: string | null;
+}
+
+/** Strip a single leading 'v' so a release ref (v1.2.3) becomes an npm version (1.2.3). */
+function toNpmVersion(repoRef: string): string {
+  return repoRef.replace(/^v/, '');
+}
+
+/**
+ * The npm dist-tag channel a release stream tracks: prereleases ride `next`,
+ * stable rides `latest`. `@openpalm/ui` is independently versioned (it publishes
+ * on its own `publish-ui.yml` workflow, like the channel adapters), so the
+ * desktop/host updaters can't compare a UI version against the app version —
+ * they pick the CHANNEL from the app's release stream and then resolve the
+ * newest UI on that channel.
  */
-/** SHA-256 hex digest of arbitrary bytes. */
-function sha256Hex(data: Uint8Array): string {
-  return createHash('sha256').update(data).digest('hex');
+export function uiUpdateChannel(appVersion: string): 'latest' | 'next' {
+  return appVersion.includes('-') ? 'next' : 'latest';
 }
 
 /**
- * Parse a `sha256sum`-format checksums file into a filename→hash map.
- * Each line is: `<hash>  <filename>` (one or two spaces).
+ * Resolve the npm manifest for `@openpalm/ui` by exact version OR dist-tag.
+ * `GET <registry>/@openpalm/ui/<version-or-tag>` returns the abbreviated
+ * manifest (version + dist.tarball + dist.integrity). Throws on non-OK.
  */
-function parseChecksumsFile(content: string): Map<string, string> {
-  const map = new Map<string, string>();
-  for (const line of content.trim().split('\n')) {
-    const parts = line.trim().split(/\s+/);
-    if (parts.length >= 2) {
-      map.set(parts[parts.length - 1], parts[0]);
+async function fetchNpmUiManifest(versionOrTag: string): Promise<NpmUiManifest> {
+  const url = `${NPM_REGISTRY}/${UI_PACKAGE}/${versionOrTag}`;
+  const res = await fetchWithRetry(url);
+  if (!res.ok) throw new Error(`npm registry returned HTTP ${res.status} for ${UI_PACKAGE}@${versionOrTag}`);
+  const m = await res.json() as { version?: string; dist?: { tarball?: string; integrity?: string } };
+  if (!m.version || !m.dist?.tarball) {
+    throw new Error(`npm manifest for ${UI_PACKAGE}@${versionOrTag} is missing version/dist.tarball`);
+  }
+  return { version: m.version, tarball: m.dist.tarball, integrity: m.dist.integrity ?? null };
+}
+
+/**
+ * Verify a Subresource-Integrity string against the bytes. FAIL-CLOSED: a
+ * present-but-wrong hash throws (the corruption / tamper case). A registry that
+ * omits the hash entirely (legacy metadata) is logged and allowed — modern npm
+ * always provides one, so this only affects pathological registry responses.
+ */
+function verifyNpmIntegrity(data: Uint8Array, integrity: string): void {
+  const entries = integrity.trim().split(/\s+/);
+  const entry = entries.find(e => e.startsWith('sha512-')) ?? entries.find(e => e.startsWith('sha256-'));
+  if (!entry) throw new Error(`unrecognized integrity format: ${integrity}`);
+  const dash = entry.indexOf('-');
+  const algo = entry.slice(0, dash);
+  const expected = entry.slice(dash + 1);
+  const actual = createHash(algo).update(data).digest('base64');
+  if (actual !== expected) throw new Error(`UI bundle integrity mismatch (${algo})`);
+}
+
+/**
+ * Download `@openpalm/ui`'s npm tarball, verify integrity, and install its
+ * `build/` contents into `uiDir`. npm tarballs nest everything under `package/`
+ * and we publish `files: ["build"]`, so the bundle lives at `package/build/**` —
+ * strip 2 path components and filter to that subtree.
+ *
+ * FAIL-CLOSED + non-destructive: we throw if integrity is missing or mismatched
+ * (the contract is that npm always provides a sha512), and we extract into a
+ * STAGING dir and validate it has a runnable `index.js` before swapping it over
+ * `uiDir` — so a truncated download or bad tarball never leaves `uiDir` empty.
+ */
+async function downloadNpmUiBundle(manifest: NpmUiManifest, uiDir: string, dataDir: string): Promise<void> {
+  const res = await fetchWithRetry(manifest.tarball);
+  if (!res.ok) throw new Error(`Failed to download UI bundle (HTTP ${res.status})`);
+  const data = new Uint8Array(await res.arrayBuffer());
+
+  // Verify BEFORE touching anything. Fail closed: a missing hash is treated as a
+  // verification failure, not a warning — modern npm always supplies dist.integrity,
+  // so its absence means a non-canonical/altered registry response.
+  if (!manifest.integrity) {
+    throw new Error(`npm manifest for ${UI_PACKAGE}@${manifest.version} has no integrity hash — refusing to install unverified`);
+  }
+  verifyNpmIntegrity(data, manifest.integrity);
+  logger.debug('UI bundle integrity verified', { version: manifest.version });
+
+  const tmpTar  = join(dataDir, '.ui-build.tgz.tmp');
+  const staging = join(dataDir, '.ui-build.staging');
+  try {
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    writeFileSync(tmpTar, data);
+    await tarExtract({
+      file: tmpTar,
+      cwd: staging,
+      strip: 2,
+      filter: (p) => p.startsWith('package/build/'),
+    });
+    // Validate the staged build is runnable before destroying the live one.
+    if (!existsSync(join(staging, 'index.js'))) {
+      throw new Error('downloaded UI bundle is missing build/index.js');
     }
+    // Swap: only now do we remove the existing build and move staging into place.
+    rmSync(uiDir, { recursive: true, force: true });
+    renameSync(staging, uiDir);
+  } finally {
+    rmSync(tmpTar, { force: true });
+    rmSync(staging, { recursive: true, force: true });
   }
-  return map;
 }
 
+/**
+ * Install the UI build to OP_HOME/data/ui/.
+ *
+ * Copies from the local/bundled `packages/ui/build/` when available, otherwise
+ * downloads the `@openpalm/ui` bundle from npm (by exact version; `repoRef` may
+ * be a tag like `latest`/`next` via the admin route). Always replaces existing
+ * content. data/ui/ is included in backups because backupOpenPalmHome() copies
+ * all of OP_HOME/data/.
+ */
 export async function seedUiBuild(repoRef: string, dataDir: string, options?: { forceRemote?: boolean }): Promise<void> {
   const uiDir = join(dataDir, 'ui');
   mkdirSync(uiDir, { recursive: true });
@@ -301,54 +401,23 @@ export async function seedUiBuild(repoRef: string, dataDir: string, options?: {
   if (local) {
     logger.debug('seeding UI build from local source', { src: local });
     copyTree(local, uiDir);
+    // The build script (stamp-version.mjs) writes .openpalm-ui-version into build/.
+    // A local build missing it would seed an UNSTAMPED data/ui, which makes the
+    // update check unable to read the running UI version. Surface it loudly rather
+    // than silently degrade update behavior.
+    if (!readUiBuildVersion(uiDir)) {
+      logger.warn('seeded UI build has no version stamp — auto-update comparison will be unreliable', { src: local });
+    }
     return;
   }
 
-  const base         = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${repoRef}`;
-  const tarballUrl   = `${base}/ui-build.tar.gz`;
-  const checksumUrl  = `${base}/checksums-sha256.txt`;
-  logger.debug('downloading UI build', { url: tarballUrl });
-
-  const tmpTar = join(dataDir, '.ui-build.tar.gz.tmp');
-  try {
-    // Download tarball and checksums file in parallel (checksums best-effort)
-    const [tarRes, csRes] = await Promise.all([
-      fetchWithRetry(tarballUrl),
-      fetchWithRetry(checksumUrl).catch(() => null),
-    ]);
-    if (!tarRes.ok) throw new Error(`Failed to download UI build (HTTP ${tarRes.status})`);
-
-    const tarData = new Uint8Array(await tarRes.arrayBuffer());
-
-    // Verify SHA-256 if the checksums file was available
-    if (csRes?.ok) {
-      const checksums = parseChecksumsFile(await csRes.text());
-      const expected  = checksums.get('ui-build.tar.gz');
-      if (expected) {
-        const actual = sha256Hex(tarData);
-        if (actual !== expected) {
-          throw new Error(`UI build checksum mismatch (expected ${expected}, got ${actual})`);
-        }
-        logger.debug('UI build checksum verified', { sha256: actual });
-      }
-    }
-
-    writeFileSync(tmpTar, tarData);
-
-    // Clear stale files before extracting so old build files don't persist
-    rmSync(uiDir, { recursive: true, force: true });
-    mkdirSync(uiDir, { recursive: true });
-    // Cross-platform extraction via the `tar` npm package — no shell dependency
-    await tarExtract({ file: tmpTar, cwd: uiDir, strip: 1 });
-  } finally {
-    rmSync(tmpTar, { force: true });
-  }
+  const manifest = await fetchNpmUiManifest(toNpmVersion(repoRef));
+  logger.debug('downloading UI build from npm', { version: manifest.version });
+  await downloadNpmUiBundle(manifest, uiDir, dataDir);
 }
 
 // ── UI update check ──────────────────────────────────────────────────────────
 
-const GITHUB_API = 'https://api.github.com';
-
 /** Returns 1 if a > b, -1 if a < b, 0 if equal. Strips leading 'v'. Handles pre-release tags. */
 function compareVersionTags(a: string, b: string): number {
   const parse = (v: string): [number, number, number, string | null] => {
@@ -398,48 +467,50 @@ export interface UiBuildUpdateResult {
 }
 
 /**
- * Check GitHub for a newer UI build and apply it if one exists.
+ * Check npm for a newer `@openpalm/ui` build and apply it if one exists.
+ *
+ * `@openpalm/ui` is INDEPENDENTLY versioned, so we do NOT compare against the
+ * app/platform version. We pick the dist-tag CHANNEL from the app's release
+ * stream (`appVersion`: prerelease → `next`, stable → `latest`) and compare the
+ * newest UI on that channel against the version actually on disk (the stamp in
+ * the resolved build). This tracks prerelease UIs for prerelease apps and fixes
+ * the `releases/latest`-excludes-prereleases blind spot.
  *
  * When an update is available:
  *   1. Move data/ui/ → data/backups/ui-{timestamp}/ (preserves the old build)
- *   2. Download ui-build.tar.gz from the latest release and extract to data/ui/
+ *   2. Download the npm bundle (integrity-verified) and extract to data/ui/
  *
  * Non-fatal: any network or extraction error returns { updated: false, error }.
  * The caller should proceed with the existing build on failure.
  */
 export async function checkAndUpdateUiBuild(
-  currentVersion: string,
+  appVersion: string,
   dataDir: string,
 ): Promise<UiBuildUpdateResult> {
   try {
-    const res = await fetch(
-      `${GITHUB_API}/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`,
-      {
-        headers: { 'User-Agent': `OpenPalm/${currentVersion}` },
-        signal: AbortSignal.timeout(10_000),
-      },
-    );
-    if (!res.ok) {
-      return { updated: false, latestVersion: null, error: `GitHub API returned ${res.status}` };
-    }
-
-    const release = await res.json() as {
-      tag_name: string;
-      assets: Array<{ name: string }>;
-    };
-    const latestTag     = release.tag_name;           // e.g. "v0.11.0"
-    const latestVersion = latestTag.replace(/^v/, '');
-
-    if (compareVersionTags(latestTag, currentVersion) <= 0) {
-      logger.debug('UI build is up to date', { current: currentVersion, latest: latestVersion });
+    const channel  = uiUpdateChannel(appVersion);
+    const manifest = await fetchNpmUiManifest(channel);
+    const latestVersion = manifest.version;
+
+    // Compare against the UI build currently on disk, NOT the app version — the
+    // UI floats on its own version line, so the platform/app version is not
+    // comparable. If the build is unstamped (e.g. a legacy data/ui seeded by the
+    // old GitHub-asset path before npm distribution), we cannot compare, so we
+    // refresh once from npm — the npm bundle is stamped, so it self-heals to the
+    // normal compare path on the next launch. Do NOT fall back to appVersion:
+    // comparing two independent version lines silently suppresses real updates.
+    const currentUiVersion = readUiBuildVersion(resolveUiBuildDir());
+
+    if (currentUiVersion && compareVersionTags(latestVersion, currentUiVersion) <= 0) {
+      logger.debug('UI build is up to date', { currentUi: currentUiVersion, latest: latestVersion, channel });
       return { updated: false, latestVersion };
     }
-
-    if (!release.assets.some(a => a.name === 'ui-build.tar.gz')) {
-      return { updated: false, latestVersion, error: 'Latest release has no ui-build.tar.gz' };
+    if (!currentUiVersion) {
+      logger.debug('UI build is unstamped — refreshing from npm to re-establish a known version', { latest: latestVersion, channel });
     }
 
-    // Back up the existing UI build before replacing it
+    // Back up the existing UI build before replacing it. (Automatic rollback on
+    // a failed start is deferred — see ui-distribution-gap-analysis.md G1.)
     const uiDir = join(dataDir, 'ui');
     if (existsSync(join(uiDir, 'index.js'))) {
       const backupDir = join(resolveBackupsDir(), `ui-${Date.now()}`);
@@ -448,8 +519,8 @@ export async function checkAndUpdateUiBuild(
       logger.debug('backed up UI build before update', { backup: backupDir });
     }
 
-    await seedUiBuild(latestTag, dataDir);
-    logger.debug('UI build updated', { from: currentVersion, to: latestVersion });
+    await downloadNpmUiBundle(manifest, uiDir, dataDir);
+    logger.debug('UI build updated', { from: currentUiVersion ?? '(unstamped)', to: latestVersion });
 
     return { updated: true, latestVersion };
   } catch (err) {

package/src/index.ts

@@ -380,4 +380,5 @@ export {
   resolveUiBuildDir,
   seedUiBuild,
   checkAndUpdateUiBuild,
+  uiUpdateChannel,
 } from "./control-plane/ui-assets.js";