@serfab/cadre-host 0.7.1 → 0.9.0

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

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { generateKeyPairSync, type KeyObject } from 'node:crypto';
+
+import { buildManifest, derivePublicKeyBase64, signAndSelfVerify, type ManifestFields } from '../sign.js';
+import { verifyManifest } from '../manifest.js';
+
+function freshKeypair(): { privateKey: KeyObject; publicRawB64: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const spki = publicKey.export({ format: 'der', type: 'spki' });
+  return { privateKey, publicRawB64: Buffer.from(spki.subarray(12)).toString('base64') };
+}
+
+const validFields: ManifestFields = {
+  version: '0.7.0',
+  package: '@serfab/cadre-host',
+  tag: 'latest',
+  publishedAt: '2026-05-15T18:00:00.000Z',
+  releaseNotesUrl: 'https://example.com/notes',
+  minPreviousVersion: '0.6.0',
+};
+
+describe('buildManifest', () => {
+  it('constructs a well-formed manifest from flat fields', () => {
+    expect(buildManifest(validFields)).toEqual({
+      v: 1,
+      version: '0.7.0',
+      publishedAt: '2026-05-15T18:00:00.000Z',
+      channels: { npm: { package: '@serfab/cadre-host', tag: 'latest' } },
+      releaseNotesUrl: 'https://example.com/notes',
+      minPreviousVersion: '0.6.0',
+    });
+  });
+
+  it('omits optional fields when not provided', () => {
+    const m = buildManifest({ version: '1.0.0', package: 'pkg', tag: 'latest', publishedAt: '2026-01-01T00:00:00.000Z' });
+    expect(m.releaseNotesUrl).toBeUndefined();
+    expect(m.minPreviousVersion).toBeUndefined();
+  });
+
+  it('rejects a bad semver version', () => {
+    expect(() => buildManifest({ ...validFields, version: 'not-semver' })).toThrow(/not a valid semver/i);
+  });
+
+  it('rejects a bad npm package name', () => {
+    expect(() => buildManifest({ ...validFields, package: 'BAD CHARS!' })).toThrow(/not a valid npm package name/i);
+  });
+
+  it('rejects a non-ISO publishedAt', () => {
+    expect(() => buildManifest({ ...validFields, publishedAt: 'last tuesday' })).toThrow(/ISO-8601/i);
+  });
+
+  it('rejects a bad minPreviousVersion', () => {
+    expect(() => buildManifest({ ...validFields, minPreviousVersion: '0.6' })).toThrow(/minPreviousVersion.*not a valid semver/i);
+  });
+});
+
+describe('signAndSelfVerify', () => {
+  afterEach(() => { delete process.env.CADRE_HOST_UPDATE_DEV_KEY; });
+
+  it('produces an envelope that verifies against the derived public key', () => {
+    const kp = freshKeypair();
+    const manifest = buildManifest(validFields);
+    const envelope = signAndSelfVerify(manifest, kp.privateKey);
+    // derivePublicKeyBase64 must agree with the independently-extracted raw key.
+    expect(derivePublicKeyBase64(kp.privateKey)).toBe(kp.publicRawB64);
+    // Independent verification against the derived key round-trips the manifest.
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = kp.publicRawB64;
+    expect(verifyManifest(envelope)).toEqual(manifest);
+  });
+
+  it('the self-verify rejects verification against a different key', () => {
+    const kp = freshKeypair();
+    const other = freshKeypair();
+    const envelope = signAndSelfVerify(buildManifest(validFields), kp.privateKey);
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = other.publicRawB64;
+    expect(() => verifyManifest(envelope)).toThrow(/signature/i);
+  });
+});

package/src/update/__tests__/update-service.integration.test.ts

@@ -4,8 +4,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { generateKeyPairSync, type KeyObject } from 'node:crypto';
 
-import { signManifestForTesting } from '../manifest.js';
+import { signManifest } from '../manifest.js';
 import { UpdateService } from '../index.js';
+import { UpdateStateStore } from '../store.js';
 import type { UpdateManifest } from '../types.js';
 
 function freshKeypair(): { privateKey: KeyObject; publicRawB64: string } {
@@ -50,7 +51,7 @@ describe('UpdateService', () => {
   });
 
   it('check(): records an available update when manifest > current', async () => {
-    const envelope = signManifestForTesting(manifest('0.7.0', { releaseNotesUrl: 'https://x' }), kp.privateKey);
+    const envelope = signManifest(manifest('0.7.0', { releaseNotesUrl: 'https://x' }), kp.privateKey);
     const svc = new UpdateService({
       dataDir: tmp,
       currentVersion: '0.6.0',
@@ -69,7 +70,7 @@ describe('UpdateService', () => {
   });
 
   it('check(): clears stale available when up-to-date', async () => {
-    const envelope = signManifestForTesting(manifest('0.6.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.6.0'), kp.privateKey);
     const svc = new UpdateService({
       dataDir: tmp,
       currentVersion: '0.7.0',
@@ -96,7 +97,7 @@ describe('UpdateService', () => {
   });
 
   it('check(): records signature_invalid as lastError', async () => {
-    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.7.0'), kp.privateKey);
     // Swap the trusted key after signing.
     const other = freshKeypair();
     process.env.CADRE_HOST_UPDATE_DEV_KEY = other.publicRawB64;
@@ -113,7 +114,7 @@ describe('UpdateService', () => {
   });
 
   it('apply(): records applyInProgress, calls npm + restart, clears on success', async () => {
-    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.7.0'), kp.privateKey);
     const calls: string[][] = [];
     const svc = new UpdateService({
       dataDir: tmp,
@@ -132,7 +133,7 @@ describe('UpdateService', () => {
   });
 
   it('apply(): rejects when current is below minPreviousVersion', async () => {
-    const envelope = signManifestForTesting(manifest('0.8.0', { minPreviousVersion: '0.7.0' }), kp.privateKey);
+    const envelope = signManifest(manifest('0.8.0', { minPreviousVersion: '0.7.0' }), kp.privateKey);
     const svc = new UpdateService({
       dataDir: tmp,
       currentVersion: '0.6.0',
@@ -143,7 +144,7 @@ describe('UpdateService', () => {
   });
 
   it('apply(): rejects when current >= latest', async () => {
-    const envelope = signManifestForTesting(manifest('0.6.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.6.0'), kp.privateKey);
     const svc = new UpdateService({
       dataDir: tmp,
       currentVersion: '0.7.0',
@@ -154,7 +155,7 @@ describe('UpdateService', () => {
   });
 
   it('apply(): records lastError + clears applyInProgress when npm install fails', async () => {
-    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.7.0'), kp.privateKey);
     let installCount = 0;
     const svc = new UpdateService({
       dataDir: tmp,
@@ -188,7 +189,7 @@ describe('UpdateService', () => {
   });
 
   it('autoApply: check() triggers apply when settings.autoApply is true', async () => {
-    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const envelope = signManifest(manifest('0.7.0'), kp.privateKey);
     const calls: string[][] = [];
     const svc = new UpdateService({
       dataDir: tmp,
@@ -203,6 +204,40 @@ describe('UpdateService', () => {
     expect(calls.some((c) => c[2] === '@serfab/cadre-host@0.7.0')).toBe(true);
   });
 
+  it('recovers from a stale applyInProgress at construction time', async () => {
+    // Simulate a crash: write a state file that records an in-flight apply.
+    const seed = new UpdateStateStore(tmp);
+    seed.update({
+      applyInProgress: {
+        fromVersion: '0.6.0',
+        toVersion: '0.7.0',
+        startedAt: '2026-05-15T18:00:00.000Z',
+      },
+    });
+
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch({}),
+      manifestUrl: 'https://example.com/m',
+    });
+    const state = await svc.getState();
+    expect(state.applyInProgress).toBeUndefined();
+    expect(state.lastError?.code).toBe('apply_failed');
+    expect(state.lastError?.message).toMatch(/interrupted/i);
+
+    // Now apply() must not short-circuit on apply_in_progress; with a stub
+    // manifest mismatch we expect the usual no_update_available path instead.
+    const envelope = signManifest(manifest('0.6.0'), kp.privateKey);
+    const svc2 = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.7.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await expect(svc2.apply()).rejects.toMatchObject({ code: 'no_update_available' });
+  });
+
   it('start()/stop(): timer can be armed and cleared', async () => {
     const svc = new UpdateService({
       dataDir: tmp,

package/src/update/apply.ts

@@ -116,12 +116,25 @@ async function tryRollback(
   }
 }
 
-/** Default executor: spawn `npm` with the given args. Adds a hard timeout. */
+/**
+ * Default executor: spawn `npm` with the given args. Adds a hard timeout.
+ *
+ * On Windows, npm ships as `npm.cmd` (a batch file). CreateProcess can't run
+ * batch files directly, so a shell is required — but Node's DEP0190 warns
+ * against `spawn(cmd, args, { shell: true })` because args are concatenated
+ * (not escaped) into the resulting command line. To dodge the deprecation we
+ * pre-quote each arg ourselves and pass the result as a single command string
+ * with an empty args array. Inputs come from a signed manifest after
+ * regex-validated package + semver checks, so injection surface is minimal;
+ * quoting is defense in depth.
+ */
 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 });
+    const spawnSpec = buildNpmSpawnSpec(args);
+    const child = spawn(spawnSpec.command, spawnSpec.args, {
+      shell: spawnSpec.shell,
+      windowsHide: true,
+    });
     let stdout = '';
     let stderr = '';
     child.stdout?.on('data', (chunk: Buffer | string) => { stdout += String(chunk); });
@@ -143,6 +156,35 @@ export function defaultNpmExecutor(timeoutMs: number): NpmExecutor {
   });
 }
 
+/**
+ * Build the `(command, args, shell)` triple passed to `spawn`. Exported for
+ * tests — the spawn shape differs per platform and the quoting matters.
+ */
+export function buildNpmSpawnSpec(args: string[]): { command: string; args: string[]; shell: boolean } {
+  if (process.platform === 'win32') {
+    const commandLine = ['npm', ...args.map(quoteWindowsArg)].join(' ');
+    return { command: commandLine, args: [], shell: true };
+  }
+  return { command: 'npm', args, shell: false };
+}
+
+/** cmd.exe quoting — wrap args containing whitespace or shell metachars. */
+export function quoteWindowsArg(arg: string): string {
+  // \x00 is an intentional security guard: reject NUL/CR/LF in args before they
+  // reach the cmd.exe command line. The control char is the point of the check.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00\r\n]/.test(arg)) {
+    throw new Error('refusing to spawn npm with control character in argument');
+  }
+  if (arg.length === 0) return '""';
+  if (!/[\s"&|<>^()%!]/.test(arg)) return arg;
+  // Escape backslashes preceding a quote per MSVCRT/cmd rules, then double the
+  // quote itself (the cmd-friendly form rather than backslash-quote).
+  const escaped = arg.replace(/(\\*)"/g, (_m, slashes: string) => slashes + slashes + '\\"');
+  const trailing = escaped.replace(/(\\*)$/, (_m, slashes: string) => slashes + slashes);
+  return `"${trailing}"`;
+}
+
 function tail(s: string, n: number): string {
   return s.length <= n ? s : '…' + s.slice(-n);
 }

package/src/update/index.ts

@@ -23,6 +23,7 @@ import {
   DEFAULT_MANIFEST_URL,
   fetchManifest,
 } from './manifest.js';
+import { isPlaceholderReleaseKey } from './release-key.js';
 import { UpdateStateStore } from './store.js';
 import {
   UpdateErrorException,
@@ -94,6 +95,31 @@ export class UpdateService {
     this.checkIntervalMs = opts.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
     this.settings = opts.settings ?? { autoApply: false };
     this.manifestUrl = resolveManifestUrl(opts.manifestUrl, this.settings.manifestUrl);
+    this.recoverInterruptedApply();
+  }
+
+  /**
+   * If `update-state.json` still records an in-flight apply at construction
+   * time, the previous cadre-host process died mid-apply (OOM, power loss,
+   * sigkill). Without intervention, every subsequent `apply()` would short-
+   * circuit on `apply_in_progress` forever. We clear the marker and surface a
+   * `lastError` so the UI banner can flag that an apply was interrupted —
+   * the npm install may or may not have completed, so the operator should
+   * verify with `npm ls -g`.
+   */
+  private recoverInterruptedApply(): void {
+    const state = this.store.load();
+    if (!state.applyInProgress) return;
+    const { fromVersion, toVersion } = state.applyInProgress;
+    log('clearing stale applyInProgress (%s → %s); previous apply was interrupted', fromVersion, toVersion);
+    this.store.update({
+      applyInProgress: undefined,
+      lastError: {
+        code: 'apply_failed',
+        message: `previous apply (${fromVersion} → ${toVersion}) was interrupted (cadre-host restarted before it completed); the install may or may not have succeeded — verify with 'npm ls -g'`,
+        at: new Date().toISOString(),
+      },
+    });
   }
 
   /** Read the persisted state for UI consumption. */
@@ -128,6 +154,12 @@ export class UpdateService {
    * debug; signature failures are recorded as `lastError` so the UI can warn.
    */
   async check(): Promise<void> {
+    if (isPlaceholderReleaseKey()) {
+      // A build that shipped the all-zeros placeholder rejects every authentic
+      // manifest as signature_invalid; surface that here so it's diagnosable
+      // from logs rather than only as an opaque verification failure.
+      log('release verification key is the all-zeros placeholder; production manifests will fail signature_invalid (set CADRE_HOST_UPDATE_DEV_KEY for dev/CI only)');
+    }
     let manifest: UpdateManifest;
     try {
       manifest = await fetchManifest({
@@ -294,10 +326,16 @@ function resolveManifestUrl(explicit: string | undefined, fromSettings: string |
   return explicit ?? fromSettings ?? DEFAULT_MANIFEST_URL;
 }
 
-export type { UpdateState, UpdateApplyResult, UpdateSettings, UpdateManifest } from './types.js';
+export type { UpdateState, UpdateApplyResult, UpdateSettings, UpdateManifest, SignedManifest } 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 { fetchManifest, verifyManifest, canonicalJson, signManifest, validateManifestFields } 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';
+export {
+  getReleasePublicKey,
+  getReleasePublicKeyBase64,
+  ed25519FromRaw,
+  isPlaceholderReleaseKey,
+} from './release-key.js';
+export { buildManifest, derivePublicKeyBase64, signAndSelfVerify, type ManifestFields } from './sign.js';