@serfab/cadre-host 0.7.1

package/src/update/release-key.ts

@@ -0,0 +1,55 @@
+/**
+ * Production Ed25519 public key used to verify the update manifest.
+ *
+ * The signing key lives offline with the release operator; only the public
+ * half ever ships in the binary.
+ *
+ * **Provisional key.** The placeholder below is regenerated whenever the
+ * release tooling is rotated — the key in this file is replaced atomically
+ * by the release build. CI keys differ from prod keys; for dev/CI overrides
+ * see `CADRE_HOST_UPDATE_DEV_KEY`.
+ */
+
+import { createPublicKey, KeyObject } from 'node:crypto';
+
+/**
+ * Raw 32-byte Ed25519 public key, base64-encoded. Placeholder pending key
+ * generation by the release op. Mismatch with the real signer will surface
+ * as `signature_invalid`, which the UI treats as "update available but
+ * unverifiable" rather than auto-applying.
+ *
+ * The real key generation/publication procedure is tracked in the
+ * release-tooling backlog; until then, the dev override below is the only
+ * supported path for CI + local manifest testing.
+ */
+const PROD_KEY_BASE64 = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+
+/**
+ * Public key (32 raw bytes, base64) — env override beats the embedded one.
+ * Used by both production and CI smoke tests.
+ */
+export function getReleasePublicKeyBase64(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.CADRE_HOST_UPDATE_DEV_KEY?.trim();
+  if (override && override.length > 0) return override;
+  return PROD_KEY_BASE64;
+}
+
+/** Lazily build the KeyObject used by `crypto.verify`. */
+export function getReleasePublicKey(env: NodeJS.ProcessEnv = process.env): KeyObject {
+  return ed25519FromRaw(getReleasePublicKeyBase64(env));
+}
+
+/**
+ * Build an Ed25519 KeyObject from a raw 32-byte base64 public key by wrapping
+ * it in the SubjectPublicKeyInfo DER prefix Node expects.
+ */
+export function ed25519FromRaw(base64Raw: string): KeyObject {
+  const raw = Buffer.from(base64Raw, 'base64');
+  if (raw.length !== 32) {
+    throw new Error(`Ed25519 public key must be 32 bytes, got ${raw.length}`);
+  }
+  // SPKI DER prefix for Ed25519: 0x302a300506032b6570032100
+  const prefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const spki = Buffer.concat([prefix, raw]);
+  return createPublicKey({ key: spki, format: 'der', type: 'spki' });
+}

package/src/update/store.ts

@@ -0,0 +1,101 @@
+/**
+ * Atomic JSON store for `<dataDir>/update-state.json`.
+ *
+ * Mirrors `TrustCircleStore` / `NatStore`: load on demand, write to
+ * `<path>.tmp` then rename. Single-writer assumption — only one cadre-host
+ * process owns a given dataDir.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import debug from 'debug';
+
+import { UpdateErrorException, type UpdateState } from './types.js';
+
+const log = debug('cadre:host:update-store');
+
+const FILE_VERSION = 1;
+const FILE_NAME = 'update-state.json';
+
+export class UpdateStateStore {
+  private readonly path: string;
+  private cache: UpdateState | null = null;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, FILE_NAME);
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  /** Load (with caching). A missing file returns an empty state. */
+  load(): UpdateState {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.path)) {
+      this.cache = { version: FILE_VERSION };
+      return this.cache;
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new UpdateErrorException(
+        'storage_error',
+        `failed to read update-state at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new UpdateErrorException(
+        'storage_error',
+        `update-state at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      throw new UpdateErrorException('storage_error', `update-state at ${this.path} is not an object`);
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (obj.version !== FILE_VERSION) {
+      throw new UpdateErrorException(
+        'unsupported_state_version',
+        `update-state at ${this.path} has unsupported version ${String(obj.version)}`,
+      );
+    }
+    this.cache = obj as unknown as UpdateState;
+    return this.cache;
+  }
+
+  /** Persist a new state atomically. */
+  save(state: UpdateState): void {
+    const next: UpdateState = { ...state, version: FILE_VERSION };
+    const payload = JSON.stringify(next, null, 2) + '\n';
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+    this.cache = next;
+    log('saved update-state.json (available=%s, applying=%s) to %s',
+      next.available?.version ?? '-',
+      next.applyInProgress ? `${next.applyInProgress.fromVersion}→${next.applyInProgress.toVersion}` : '-',
+      this.path);
+  }
+
+  /** Merge a patch into the current state and persist. */
+  update(patch: Partial<Omit<UpdateState, 'version'>>): UpdateState {
+    const current = this.load();
+    const next: UpdateState = { ...current, ...patch, version: FILE_VERSION };
+    this.save(next);
+    return next;
+  }
+
+  /** Drop a specific field from the persisted state. */
+  clearField<K extends keyof Omit<UpdateState, 'version'>>(field: K): UpdateState {
+    const current = { ...this.load() };
+    delete current[field];
+    this.save(current);
+    return current;
+  }
+}

package/src/update/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Types for the cadre-host update flow.
+ *
+ * The update flow is split across:
+ *
+ *   - manifest.ts — fetch + verify the signed `latest.json` envelope.
+ *   - store.ts    — persist the user-facing `UpdateState` to `<dataDir>/update-state.json`.
+ *   - apply.ts    — invoke `npm install -g` + rollback on failure.
+ *   - index.ts    — composes the above (UpdateService).
+ *
+ * Mirrors the typed-handler pattern used by trust-circle and NAT (handlers
+ * throw `UpdateError` whose `.code` the local-UI maps to HTTP status).
+ */
+
+/** Inner manifest object — signed by the release key. */
+export interface UpdateManifest {
+  /** Schema version. Bumped on incompatible manifest changes. */
+  v: 1;
+  /** Version string being announced (semver). */
+  version: string;
+  /** ISO publish timestamp. */
+  publishedAt: string;
+  /** Per-channel install hints. cadre-host currently only consults `npm`. */
+  channels: {
+    npm: { package: string; tag: string };
+  };
+  /** Optional human-facing release-notes URL. */
+  releaseNotesUrl?: string;
+  /**
+   * Minimum previous version that can step directly to this release. If the
+   * current install is older, the user must update through an intermediate
+   * release first.
+   */
+  minPreviousVersion?: string;
+}
+
+/** Signed envelope as fetched from the manifest URL. */
+export interface SignedManifest {
+  manifest: UpdateManifest;
+  /** Detached signature in the form `ed25519:<base64>`. */
+  sig: string;
+}
+
+/** Persisted shape of `<dataDir>/update-state.json`. */
+export interface UpdateState {
+  /** Schema version of this file. */
+  version: 1;
+  /** ISO timestamp of the most recent successful manifest fetch. */
+  lastChecked?: string;
+  /** Set when the manifest advertises a version newer than `currentVersion`. */
+  available?: {
+    version: string;
+    publishedAt: string;
+    releaseNotesUrl?: string;
+  };
+  /** Records the version before an apply, so a rollback can target it. */
+  applyInProgress?: {
+    fromVersion: string;
+    toVersion: string;
+    startedAt: string;
+  };
+  /** Most recent apply / verification error, surfaced by the UI banner. */
+  lastError?: UpdateError;
+}
+
+/** Stable error payload — both thrown via `UpdateErrorException` and serialized into state. */
+export interface UpdateError {
+  code: UpdateErrorCode;
+  message: string;
+  at: string;
+}
+
+export type UpdateErrorCode =
+  | 'signature_invalid'
+  | 'manifest_invalid'
+  | 'unsupported_state_version'
+  | 'apply_in_progress'
+  | 'apply_failed'
+  | 'rollback_failed'
+  | 'min_previous_version'
+  | 'no_update_available'
+  | 'storage_error';
+
+/** Thrown by UpdateService.apply() and related entry points. */
+export class UpdateErrorException extends Error {
+  readonly code: UpdateErrorCode;
+
+  constructor(code: UpdateErrorCode, message: string) {
+    super(message);
+    this.name = 'UpdateErrorException';
+    this.code = code;
+  }
+}
+
+/** Result of a successful apply() — the caller can inspect what just happened. */
+export interface UpdateApplyResult {
+  fromVersion: string;
+  toVersion: string;
+  restarted: boolean;
+  restartError?: string;
+}
+
+/** Subset of `host.config.json` consumed by the update flow. */
+export interface UpdateSettings {
+  /** When true, the daily timer applies updates automatically. */
+  autoApply: boolean;
+  /** Optional override for the manifest URL. */
+  manifestUrl?: string;
+}

package/src/update/version.ts

@@ -0,0 +1,80 @@
+/**
+ * Tiny semver comparator. We refuse to pull in `semver` for a single
+ * compareVersions() call; the surface here is intentionally narrow.
+ *
+ * Supports `MAJOR.MINOR.PATCH` and `MAJOR.MINOR.PATCH-PRERELEASE` (semver §11).
+ * Build metadata (`+...`) is rejected — releases shouldn't ship with it and
+ * it'd only confuse equality.
+ */
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Empty string when there is no prerelease (= a higher precedence release). */
+  prerelease: string;
+}
+
+export function parseVersion(input: string): ParsedVersion {
+  if (typeof input !== 'string') {
+    throw new Error(`Invalid version: ${String(input)}`);
+  }
+  const m = SEMVER_RE.exec(input.trim());
+  if (!m) {
+    throw new Error(`Invalid version: ${input}`);
+  }
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ?? '',
+  };
+}
+
+/** -1 if a < b, 0 if equal, +1 if a > b. */
+export function compareVersions(a: string, b: string): number {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+
+  // Per semver §11: a version *without* a prerelease has higher precedence
+  // than one with a prerelease.
+  if (pa.prerelease === '' && pb.prerelease === '') return 0;
+  if (pa.prerelease === '') return 1;
+  if (pb.prerelease === '') return -1;
+
+  return comparePrerelease(pa.prerelease, pb.prerelease);
+}
+
+/** Component-wise compare per semver §11.4. */
+function comparePrerelease(a: string, b: string): number {
+  const as = a.split('.');
+  const bs = b.split('.');
+  const len = Math.min(as.length, bs.length);
+  for (let i = 0; i < len; i++) {
+    const c = compareIdentifier(as[i]!, bs[i]!);
+    if (c !== 0) return c;
+  }
+  if (as.length === bs.length) return 0;
+  return as.length < bs.length ? -1 : 1;
+}
+
+function compareIdentifier(a: string, b: string): number {
+  const aNum = /^\d+$/.test(a);
+  const bNum = /^\d+$/.test(b);
+  if (aNum && bNum) {
+    const na = Number(a);
+    const nb = Number(b);
+    return na === nb ? 0 : na < nb ? -1 : 1;
+  }
+  // Numeric identifiers always have lower precedence than alphanumeric.
+  if (aNum) return -1;
+  if (bNum) return 1;
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}