@serfab/cadre-host 0.7.1

package/src/update/__tests__/version.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { compareVersions, parseVersion } from '../version.js';
+
+describe('compareVersions', () => {
+  it('orders releases by major/minor/patch', () => {
+    expect(compareVersions('0.6.0', '0.7.0')).toBeLessThan(0);
+    expect(compareVersions('1.0.0', '0.99.99')).toBeGreaterThan(0);
+    expect(compareVersions('1.2.3', '1.2.3')).toBe(0);
+    expect(compareVersions('1.2.4', '1.2.3')).toBeGreaterThan(0);
+  });
+
+  it('puts prereleases below their associated release (semver §11)', () => {
+    expect(compareVersions('0.7.0-rc1', '0.7.0')).toBeLessThan(0);
+    expect(compareVersions('0.7.0', '0.7.0-rc1')).toBeGreaterThan(0);
+  });
+
+  it('compares prereleases by identifier with numeric < alphanumeric', () => {
+    expect(compareVersions('0.7.0-alpha', '0.7.0-beta')).toBeLessThan(0);
+    expect(compareVersions('0.7.0-rc.1', '0.7.0-rc.2')).toBeLessThan(0);
+    expect(compareVersions('0.7.0-rc.2', '0.7.0-rc.10')).toBeLessThan(0);
+    expect(compareVersions('0.7.0-1', '0.7.0-rc')).toBeLessThan(0);
+  });
+
+  it('rejects ill-formed input', () => {
+    expect(() => parseVersion('not a version')).toThrow(/Invalid version/);
+    expect(() => parseVersion('1.2')).toThrow(/Invalid version/);
+    expect(() => parseVersion('1.2.3+build')).toThrow(/Invalid version/);
+    expect(() => compareVersions('1.2.3', '1.x.0')).toThrow(/Invalid version/);
+  });
+});

package/src/update/apply.ts

@@ -0,0 +1,148 @@
+/**
+ * Apply an update.
+ *
+ * Apply == reinstall the package globally via `npm install -g <pkg>@<ver>`.
+ * Rollback == reinstall the previously-recorded version. Both are dispatched
+ * through an injectable `NpmExecutor` so tests don't shell out.
+ *
+ * Service-host restart is best-effort: the binary swap succeeded even if
+ * `systemctl/launchctl/nssm restart` returned non-zero, so the state stays
+ * successful and the caller surfaces a warning. (User can restart by hand.)
+ */
+
+import { spawn } from 'node:child_process';
+import debug from 'debug';
+
+import {
+  UpdateErrorException,
+  type UpdateApplyResult,
+} from './types.js';
+
+const log = debug('cadre:host:update-apply');
+
+const DEFAULT_NPM_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface NpmResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Pluggable npm runner — replaced in tests. */
+export type NpmExecutor = (args: string[]) => Promise<NpmResult>;
+
+/** Optional service-host restart hook. Returns undefined on success, an error message on failure. */
+export type ServiceRestarter = () => Promise<string | undefined>;
+
+export interface ApplyOptions {
+  npmPackage: string;
+  fromVersion: string;
+  toVersion: string;
+  npmExecutor?: NpmExecutor;
+  restart?: ServiceRestarter;
+  timeoutMs?: number;
+}
+
+/**
+ * Drive the install + restart. Throws `UpdateErrorException('apply_failed')`
+ * if the install itself fails (after attempting rollback). On install
+ * success but restart failure, returns a result with the restart error set.
+ */
+export async function applyUpdate(opts: ApplyOptions): Promise<UpdateApplyResult> {
+  const executor = opts.npmExecutor ?? defaultNpmExecutor(opts.timeoutMs ?? DEFAULT_NPM_TIMEOUT_MS);
+
+  const installArgs = ['install', '-g', `${opts.npmPackage}@${opts.toVersion}`];
+  let installResult: NpmResult;
+  try {
+    installResult = await executor(installArgs);
+  } catch (err) {
+    await tryRollback(opts.npmPackage, opts.fromVersion, executor);
+    throw new UpdateErrorException(
+      'apply_failed',
+      `npm install threw: ${(err as Error).message}`,
+    );
+  }
+  if (installResult.exitCode !== 0) {
+    const stderrTail = tail(installResult.stderr || installResult.stdout, 400);
+    const rollbackErr = await tryRollback(opts.npmPackage, opts.fromVersion, executor);
+    if (rollbackErr) {
+      throw new UpdateErrorException(
+        'rollback_failed',
+        `npm install failed (exit ${installResult.exitCode}); rollback also failed: ${rollbackErr}. Original error: ${stderrTail}`,
+      );
+    }
+    throw new UpdateErrorException(
+      'apply_failed',
+      `npm install failed (exit ${installResult.exitCode}): ${stderrTail}`,
+    );
+  }
+  log('npm install -g %s@%s succeeded', opts.npmPackage, opts.toVersion);
+
+  let restartError: string | undefined;
+  if (opts.restart) {
+    try {
+      restartError = await opts.restart();
+    } catch (err) {
+      restartError = (err as Error).message;
+    }
+    if (restartError) {
+      log('service restart failed: %s', restartError);
+    }
+  }
+
+  return {
+    fromVersion: opts.fromVersion,
+    toVersion: opts.toVersion,
+    restarted: opts.restart !== undefined && restartError === undefined,
+    ...(restartError ? { restartError } : {}),
+  };
+}
+
+/** Best-effort rollback. Returns an error string if the rollback itself failed. */
+async function tryRollback(
+  pkg: string,
+  fromVersion: string,
+  executor: NpmExecutor,
+): Promise<string | undefined> {
+  log('rolling back to %s@%s', pkg, fromVersion);
+  try {
+    const rollback = await executor(['install', '-g', `${pkg}@${fromVersion}`]);
+    if (rollback.exitCode !== 0) {
+      return `npm install exit ${rollback.exitCode}: ${tail(rollback.stderr || rollback.stdout, 400)}`;
+    }
+    return undefined;
+  } catch (err) {
+    return `npm install threw: ${(err as Error).message}`;
+  }
+}
+
+/** Default executor: spawn `npm` with the given args. Adds a hard timeout. */
+export function defaultNpmExecutor(timeoutMs: number): NpmExecutor {
+  return (args: string[]) => new Promise<NpmResult>((resolveExec) => {
+    // Windows resolves `npm` via `npm.cmd`; using shell:true is the
+    // simplest cross-platform answer that still works with PATH lookup.
+    const child = spawn('npm', args, { shell: process.platform === 'win32', windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk: Buffer | string) => { stdout += String(chunk); });
+    child.stderr?.on('data', (chunk: Buffer | string) => { stderr += String(chunk); });
+
+    const timer = setTimeout(() => {
+      stderr += `\n[cadre-host] npm install timed out after ${timeoutMs}ms, killing`;
+      child.kill('SIGTERM');
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolveExec({ exitCode: 127, stdout, stderr: stderr + `\nspawn failed: ${err.message}` });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolveExec({ exitCode: code ?? -1, stdout, stderr });
+    });
+  });
+}
+
+function tail(s: string, n: number): string {
+  return s.length <= n ? s : '…' + s.slice(-n);
+}

package/src/update/index.ts

@@ -0,0 +1,303 @@
+/**
+ * UpdateService — the composition root for the cadre-host update flow.
+ *
+ * Background check cadence: once at construction time (`check()` called
+ * explicitly by `cadre-host start` after the management API binds) and a
+ * 24-hour interval timer thereafter. Failures are silent — UI consumers see
+ * `lastChecked` only when a fetch succeeds.
+ *
+ * Apply flow: re-fetch + re-verify the manifest (never trust the cached
+ * `available`), record `applyInProgress`, run `npm install -g`, restart the
+ * service via the optional `ServiceRestarter`, and roll back on failure.
+ */
+
+import debug from 'debug';
+
+import {
+  applyUpdate,
+  defaultNpmExecutor,
+  type NpmExecutor,
+  type ServiceRestarter,
+} from './apply.js';
+import {
+  DEFAULT_MANIFEST_URL,
+  fetchManifest,
+} from './manifest.js';
+import { UpdateStateStore } from './store.js';
+import {
+  UpdateErrorException,
+  type UpdateApplyResult,
+  type UpdateManifest,
+  type UpdateSettings,
+  type UpdateState,
+} from './types.js';
+import { compareVersions } from './version.js';
+
+const log = debug('cadre:host:update-service');
+
+const DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_NPM_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface UpdateServiceOptions {
+  /** cadre-host data directory; UpdateState file lives here. */
+  dataDir: string;
+  /** Currently-running package version (from package.json). */
+  currentVersion: string;
+  /** Manifest URL. Defaults: env CADRE_HOST_UPDATE_MANIFEST_URL → DEFAULT_MANIFEST_URL. */
+  manifestUrl?: string;
+  /** Fetcher (test injection). */
+  fetcher?: typeof fetch;
+  /** npm runner (test injection). */
+  npmExecutor?: NpmExecutor;
+  /** Service-host restart hook (test injection / wiring from cadre-host start). */
+  restart?: ServiceRestarter;
+  /** Initial settings (autoApply etc) — typically sourced from host.config.json. */
+  settings?: UpdateSettings;
+  /** Periodic-check interval; defaults to 24h. */
+  checkIntervalMs?: number;
+  /** npm install timeout; defaults to 5m. */
+  npmTimeoutMs?: number;
+}
+
+/** Handlers for the management-API listener. */
+export interface UpdateHandlers {
+  getState(): Promise<UpdateState>;
+  postApply(): Promise<UpdateApplyResult>;
+  getSettings(): Promise<UpdateSettings>;
+  putSettings(body: { autoApply?: boolean; manifestUrl?: string }): Promise<UpdateSettings>;
+}
+
+export class UpdateService {
+  private readonly store: UpdateStateStore;
+  private readonly currentVersion: string;
+  private readonly fetcher: typeof fetch;
+  private readonly npmExecutor: NpmExecutor;
+  private readonly restart: ServiceRestarter | undefined;
+  private readonly checkIntervalMs: number;
+  private readonly npmTimeoutMs: number;
+
+  private manifestUrl: string;
+  private settings: UpdateSettings;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private applying = false;
+
+  /** Persisted settings changes are bubbled out via this callback (wired in cadre-host start). */
+  private onSettingsChange?: (next: UpdateSettings) => void | Promise<void>;
+
+  constructor(opts: UpdateServiceOptions) {
+    this.store = new UpdateStateStore(opts.dataDir);
+    this.currentVersion = opts.currentVersion;
+    this.fetcher = opts.fetcher ?? fetch;
+    this.npmTimeoutMs = opts.npmTimeoutMs ?? DEFAULT_NPM_TIMEOUT_MS;
+    this.npmExecutor = opts.npmExecutor ?? defaultNpmExecutor(this.npmTimeoutMs);
+    this.restart = opts.restart;
+    this.checkIntervalMs = opts.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+    this.settings = opts.settings ?? { autoApply: false };
+    this.manifestUrl = resolveManifestUrl(opts.manifestUrl, this.settings.manifestUrl);
+  }
+
+  /** Read the persisted state for UI consumption. */
+  async getState(): Promise<UpdateState> {
+    return this.store.load();
+  }
+
+  /** Current settings (in-memory). */
+  getSettings(): UpdateSettings {
+    return { ...this.settings };
+  }
+
+  /**
+   * Update settings (autoApply / manifestUrl). The optional `onSettingsChange`
+   * hook is invoked so the caller can persist to host.config.json.
+   */
+  async putSettings(patch: { autoApply?: boolean; manifestUrl?: string }): Promise<UpdateSettings> {
+    if (patch.autoApply !== undefined) this.settings.autoApply = patch.autoApply;
+    if (patch.manifestUrl !== undefined) this.settings.manifestUrl = patch.manifestUrl;
+    this.manifestUrl = resolveManifestUrl(undefined, this.settings.manifestUrl);
+    if (this.onSettingsChange) await this.onSettingsChange({ ...this.settings });
+    return { ...this.settings };
+  }
+
+  /** Register the persistence hook called after every settings mutation. */
+  onSettingsChanged(handler: (next: UpdateSettings) => void | Promise<void>): void {
+    this.onSettingsChange = handler;
+  }
+
+  /**
+   * Background manifest check. Never throws — fetch/parse failures log at
+   * debug; signature failures are recorded as `lastError` so the UI can warn.
+   */
+  async check(): Promise<void> {
+    let manifest: UpdateManifest;
+    try {
+      manifest = await fetchManifest({
+        url: this.manifestUrl,
+        fetcher: this.fetcher,
+      });
+    } catch (err) {
+      if (err instanceof UpdateErrorException && err.code === 'signature_invalid') {
+        log('manifest signature invalid: %s', err.message);
+        this.store.update({
+          lastError: { code: err.code, message: err.message, at: new Date().toISOString() },
+        });
+        return;
+      }
+      // Network / parse / endpoint-down: silent.
+      log('manifest fetch failed: %s', (err as Error).message);
+      return;
+    }
+
+    const now = new Date().toISOString();
+    const compared = compareVersions(this.currentVersion, manifest.version);
+    if (compared >= 0) {
+      // Already up-to-date — clear any stale `available` record.
+      this.store.update({
+        lastChecked: now,
+        available: undefined,
+        lastError: undefined,
+      });
+      log('check ok: current %s ≥ %s', this.currentVersion, manifest.version);
+      return;
+    }
+
+    this.store.update({
+      lastChecked: now,
+      available: {
+        version: manifest.version,
+        publishedAt: manifest.publishedAt,
+        ...(manifest.releaseNotesUrl ? { releaseNotesUrl: manifest.releaseNotesUrl } : {}),
+      },
+      lastError: undefined,
+    });
+    log('update available: %s → %s', this.currentVersion, manifest.version);
+
+    if (this.settings.autoApply) {
+      try {
+        await this.apply();
+      } catch (err) {
+        // apply() already recorded the error; we just don't want to crash the timer.
+        log('auto-apply failed: %s', (err as Error).message);
+      }
+    }
+  }
+
+  /**
+   * Trigger an apply. Re-verifies the manifest, runs npm install -g, attempts
+   * a service restart, and rolls back on failure. Throws UpdateErrorException
+   * on any hard failure; success returns the new state.
+   */
+  async apply(): Promise<UpdateApplyResult> {
+    if (this.applying) {
+      throw new UpdateErrorException('apply_in_progress', 'another apply is already running');
+    }
+    const state = this.store.load();
+    if (state.applyInProgress) {
+      throw new UpdateErrorException('apply_in_progress', 'state already records an in-flight apply');
+    }
+    this.applying = true;
+    try {
+      const manifest = await fetchManifest({
+        url: this.manifestUrl,
+        fetcher: this.fetcher,
+      });
+      if (compareVersions(this.currentVersion, manifest.version) >= 0) {
+        throw new UpdateErrorException(
+          'no_update_available',
+          `current ${this.currentVersion} is already ≥ latest ${manifest.version}`,
+        );
+      }
+      if (manifest.minPreviousVersion && compareVersions(this.currentVersion, manifest.minPreviousVersion) < 0) {
+        throw new UpdateErrorException(
+          'min_previous_version',
+          `current ${this.currentVersion} is below minPreviousVersion ${manifest.minPreviousVersion}; install an intermediate release first`,
+        );
+      }
+
+      const startedAt = new Date().toISOString();
+      this.store.update({
+        applyInProgress: {
+          fromVersion: this.currentVersion,
+          toVersion: manifest.version,
+          startedAt,
+        },
+      });
+
+      try {
+        const result = await applyUpdate({
+          npmPackage: manifest.channels.npm.package,
+          fromVersion: this.currentVersion,
+          toVersion: manifest.version,
+          npmExecutor: this.npmExecutor,
+          ...(this.restart ? { restart: this.restart } : {}),
+          timeoutMs: this.npmTimeoutMs,
+        });
+        // Success: clear progress + any prior error.
+        this.store.update({
+          applyInProgress: undefined,
+          lastError: undefined,
+        });
+        return result;
+      } catch (err) {
+        const code = err instanceof UpdateErrorException ? err.code : 'apply_failed';
+        const message = (err as Error).message;
+        this.store.update({
+          applyInProgress: undefined,
+          lastError: { code, message, at: new Date().toISOString() },
+        });
+        throw err instanceof UpdateErrorException ? err : new UpdateErrorException('apply_failed', message);
+      }
+    } finally {
+      this.applying = false;
+    }
+  }
+
+  /** Start the daily-check timer. `start()` ensures we don't double-arm. */
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.check().catch((err) => log('scheduled check threw (should not happen): %s', (err as Error).message));
+    }, this.checkIntervalMs);
+    // Don't keep the event loop alive just for this timer.
+    if (typeof this.timer === 'object' && this.timer && 'unref' in this.timer) {
+      (this.timer as { unref?: () => void }).unref?.();
+    }
+  }
+
+  /** Stop the daily-check timer. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/**
+ * Typed handler facade — mirrors `createTrustCircleHandlers` /
+ * `createNatHandlers`. The local-UI ticket consumes these.
+ */
+export function createUpdateHandlers(service: UpdateService): UpdateHandlers {
+  return {
+    async getState() { return service.getState(); },
+    async postApply() { return await service.apply(); },
+    async getSettings() { return service.getSettings(); },
+    async putSettings(body) { return await service.putSettings(body); },
+  };
+}
+
+function resolveManifestUrl(explicit: string | undefined, fromSettings: string | undefined): string {
+  // Env var wins — operators routinely point this at staging endpoints, and
+  // both the README and host.ts documentation promise that behavior.
+  // Then explicit constructor arg → persisted settings → compiled default.
+  const envUrl = process.env.CADRE_HOST_UPDATE_MANIFEST_URL?.trim();
+  if (envUrl) return envUrl;
+  return explicit ?? fromSettings ?? DEFAULT_MANIFEST_URL;
+}
+
+export type { UpdateState, UpdateApplyResult, UpdateSettings, UpdateManifest } from './types.js';
+export { UpdateErrorException, type UpdateErrorCode } from './types.js';
+export { compareVersions, parseVersion } from './version.js';
+export { fetchManifest, verifyManifest, canonicalJson, signManifestForTesting } from './manifest.js';
+export { UpdateStateStore } from './store.js';
+export { applyUpdate, defaultNpmExecutor, type NpmExecutor, type ServiceRestarter } from './apply.js';
+export { getReleasePublicKey, getReleasePublicKeyBase64, ed25519FromRaw } from './release-key.js';

package/src/update/manifest.ts

@@ -0,0 +1,172 @@
+/**
+ * Fetch + verify the signed update manifest.
+ *
+ * The manifest is a JSON envelope `{ manifest, sig }` where `sig` is a
+ * detached Ed25519 signature of `canonicalJson(manifest)`. cadre-host only
+ * trusts manifests whose signature matches the embedded release public key.
+ *
+ * Canonical serialization is a tiny local impl — depending on
+ * `json-canonicalize` (or similar) for a single call site is overkill, and
+ * the shape is fixed (`UpdateManifest`).
+ */
+
+import { sign as cryptoSign, verify as cryptoVerify, type KeyObject } from 'node:crypto';
+
+import { ed25519FromRaw, getReleasePublicKey, getReleasePublicKeyBase64 } from './release-key.js';
+import {
+  UpdateErrorException,
+  type SignedManifest,
+  type UpdateManifest,
+} from './types.js';
+
+/** Default release-manifest URL. Overridable via env var on the caller. */
+export const DEFAULT_MANIFEST_URL = 'https://releases.serfab.io/cadre-host/latest.json';
+
+export interface FetchManifestOptions {
+  url: string;
+  fetcher?: typeof fetch;
+  /** Total fetch timeout (connect + read) in ms; default 10000. */
+  readTimeoutMs?: number;
+}
+
+/**
+ * Fetch the manifest endpoint and validate the signature against the embedded
+ * release public key (or `CADRE_HOST_UPDATE_DEV_KEY` if set).
+ *
+ * Throws `UpdateErrorException` on any failure (bad JSON, bad signature,
+ * etc.). Network errors are *thrown* — the caller decides whether to log
+ * them at debug (the cadence path) or surface them (the apply path).
+ */
+export async function fetchManifest(opts: FetchManifestOptions): Promise<UpdateManifest> {
+  const fetcher = opts.fetcher ?? fetch;
+  const readTimeout = opts.readTimeoutMs ?? 10_000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), readTimeout);
+  let response: Response;
+  try {
+    response = await fetcher(opts.url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response.ok) {
+    throw new Error(`manifest endpoint returned ${response.status}`);
+  }
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new UpdateErrorException(
+      'manifest_invalid',
+      `manifest is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+  return verifyManifest(body);
+}
+
+/**
+ * Verify a parsed signed-manifest body. Pure (no network), so unit tests
+ * exercise this directly.
+ */
+export function verifyManifest(
+  body: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): UpdateManifest {
+  if (!isSignedManifest(body)) {
+    throw new UpdateErrorException('manifest_invalid', 'manifest envelope is malformed');
+  }
+  if (!isUpdateManifest(body.manifest)) {
+    throw new UpdateErrorException('manifest_invalid', 'manifest payload is missing required fields');
+  }
+
+  const sig = parseSignature(body.sig);
+  const canonical = Buffer.from(canonicalJson(body.manifest), 'utf8');
+  const key = getReleasePublicKey(env);
+
+  let ok: boolean;
+  try {
+    ok = cryptoVerify(null, canonical, key, sig);
+  } catch (err) {
+    throw new UpdateErrorException(
+      'signature_invalid',
+      `signature verification threw: ${(err as Error).message}`,
+    );
+  }
+  if (!ok) {
+    throw new UpdateErrorException('signature_invalid', 'manifest signature did not verify');
+  }
+  return body.manifest;
+}
+
+/** Exposed for test signers. */
+export function signManifestForTesting(manifest: UpdateManifest, privateKey: KeyObject): SignedManifest {
+  const canonical = Buffer.from(canonicalJson(manifest), 'utf8');
+  const sig = cryptoSign(null, canonical, privateKey).toString('base64');
+  return { manifest, sig: `ed25519:${sig}` };
+}
+
+/** Used by `apply.ts` to detect which key the signer matches. */
+export function publicKeyMatchesEmbedded(rawBase64: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return rawBase64 === getReleasePublicKeyBase64(env);
+}
+
+/** Wrapper for `getReleasePublicKey`, re-exported for parity with `ed25519FromRaw`. */
+export { ed25519FromRaw };
+
+/** ---- internals ---- */
+
+function parseSignature(sig: string): Buffer {
+  const match = /^ed25519:(.+)$/.exec(sig);
+  if (!match) {
+    throw new UpdateErrorException('signature_invalid', `unsupported signature scheme: ${sig.slice(0, 16)}…`);
+  }
+  const decoded = Buffer.from(match[1]!, 'base64');
+  if (decoded.length !== 64) {
+    throw new UpdateErrorException('signature_invalid', `Ed25519 signature must be 64 bytes, got ${decoded.length}`);
+  }
+  return decoded;
+}
+
+function isSignedManifest(v: unknown): v is SignedManifest {
+  if (!v || typeof v !== 'object') return false;
+  const obj = v as Record<string, unknown>;
+  return typeof obj.sig === 'string' && obj.manifest !== undefined && typeof obj.manifest === 'object';
+}
+
+function isUpdateManifest(v: unknown): v is UpdateManifest {
+  if (!v || typeof v !== 'object') return false;
+  const o = v as Record<string, unknown>;
+  if (o.v !== 1) return false;
+  if (typeof o.version !== 'string' || o.version.length === 0) return false;
+  if (typeof o.publishedAt !== 'string') return false;
+  if (!o.channels || typeof o.channels !== 'object') return false;
+  const npm = (o.channels as Record<string, unknown>).npm as Record<string, unknown> | undefined;
+  if (!npm || typeof npm.package !== 'string' || typeof npm.tag !== 'string') return false;
+  if (o.releaseNotesUrl !== undefined && typeof o.releaseNotesUrl !== 'string') return false;
+  if (o.minPreviousVersion !== undefined && typeof o.minPreviousVersion !== 'string') return false;
+  return true;
+}
+
+/**
+ * Canonical JSON: recursively sort object keys, no whitespace, no trailing
+ * newline. Matches a typical RFC 8785 subset for the fixed shape we sign.
+ * Arrays preserve order.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('cannot serialize non-finite number');
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') + '}';
+  }
+  throw new Error(`cannot serialize value of type ${typeof value}`);
+}