@serfab/cadre-host 0.7.1 → 0.8.1

package/src/server/routes/nodes.ts

@@ -6,9 +6,10 @@
  * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
  * handlers don't re-publish.
  *
- * v1 limits: cadre-host doesn't yet auto-spawn nodes (the trust-circle →
- * node mapping ticket is separate). Until it lands, `listNodes()` is
- * usually empty and start/restart are stubs. Stop on a running node works.
+ * start/restart are real for the admin's authority node (re-spawned from the
+ * persisted `AuthoritySpawnConfig`). Generic per-member node spawn from saved
+ * config is out of scope and returns `not_implemented`. Stop works for any
+ * running node.
  */
 
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
@@ -82,35 +83,56 @@ export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptio
     return { ok: true };
   });
 
-  // start / restart: the orchestrator's createContainer requires a full
-  // OrchestratorCreateRequest (partyId, bootstrapNodes, profile, ...).
-  // cadre-host doesn't yet own a "spawn this node from saved config" path
-  // — that lives in the trust-circle-driven node spawner planned for a
-  // follow-up ticket. Until then these endpoints stub out cleanly so the
-  // SPA gets a predictable error rather than a route-not-found 404.
+  // start / restart: real for the admin's authority node (spawned from the
+  // persisted AuthoritySpawnConfig). Generic per-member node spawn from saved
+  // config is out of scope — those ids return a clear not_implemented; unknown
+  // ids 404.
   app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
-    return reply.code(501).send({
-      ok: false,
-      error: {
-        code: 'not_implemented',
-        message:
-          `start ${request.params.id}: cadre-host v1 has no auto-spawn path. ` +
-          `Restart the cadre-host service to bring up persisted nodes.`,
-      },
-    });
+    const { id } = request.params;
+    if (orchestrator.isAuthorityNode(id)) {
+      if (!orchestrator.hasAuthorityConfig()) {
+        return notImplemented(reply, `start ${id}: authority node has no saved spawn config.`);
+      }
+      const node = await orchestrator.ensureAuthorityNode();
+      return { ok: true, data: { node } };
+    }
+    return startRestartFallback(reply, orchestrator, id, 'start');
   });
 
   app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
-    return reply.code(501).send({
+    const { id } = request.params;
+    if (orchestrator.isAuthorityNode(id)) {
+      if (!orchestrator.hasAuthorityConfig()) {
+        return notImplemented(reply, `restart ${id}: authority node has no saved spawn config.`);
+      }
+      const node = await orchestrator.restartAuthorityNode();
+      return { ok: true, data: { node } };
+    }
+    return startRestartFallback(reply, orchestrator, id, 'restart');
+  });
+}
+
+/** 404 for unknown ids; 501 not_implemented for known non-authority nodes. */
+function startRestartFallback(
+  reply: import('fastify').FastifyReply,
+  orchestrator: HostProcessOrchestrator,
+  id: string,
+  verb: string,
+) {
+  if (!orchestrator.getNode(id)) {
+    return reply.code(404).send({
       ok: false,
-      error: {
-        code: 'not_implemented',
-        message:
-          `restart ${request.params.id}: cadre-host v1 has no auto-spawn path. ` +
-          `Restart the cadre-host service to bring up persisted nodes.`,
-      },
+      error: { code: 'not_found', message: `Unknown node: ${id}` },
     });
-  });
+  }
+  return notImplemented(
+    reply,
+    `${verb} ${id}: only the authority node is start/restart-able; generic node spawn is out of scope.`,
+  );
+}
+
+function notImplemented(reply: import('fastify').FastifyReply, message: string) {
+  return reply.code(501).send({ ok: false, error: { code: 'not_implemented', message } });
 }
 
 /**

package/src/server/static.ts

@@ -13,13 +13,10 @@
  */
 
 import { readFileSync, statSync, existsSync } from 'node:fs';
-import { dirname, extname, join, normalize, resolve } from 'node:path';
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-import debug from 'debug';
-
-const log = debug('cadre:host:static');
 
 const MIME_TYPES: Record<string, string> = {
   '.html': 'text/html; charset=utf-8',
@@ -118,12 +115,31 @@ function serveStatic(rootDir: string, request: FastifyRequest, reply: FastifyRep
   });
 }
 
-function resolveSafe(rootDir: string, urlPath: string): string | null {
+/**
+ * Resolve a request path to an absolute file path inside `rootDir`, or `null`
+ * if it would escape the root.
+ *
+ * Exported for direct unit testing. The containment check uses `path.relative`
+ * rather than a bare `startsWith` prefix test: the latter is the classic
+ * prefix-bypass anti-pattern, accepting sibling directories whose name shares
+ * `rootDir`'s basename as a prefix (e.g. `dist/ui-private` vs `dist/ui`).
+ * `relative` respects the path-separator boundary on both POSIX and Windows,
+ * and surfaces cross-drive escapes on Windows as an absolute result.
+ */
+export function resolveSafe(rootDir: string, urlPath: string): string | null {
   const cleaned = decodeSafe(urlPath);
   if (cleaned === null) return null;
-  const target = normalize(join(rootDir, cleaned === '/' ? '' : cleaned));
-  // Disallow path traversal above rootDir.
-  if (!target.startsWith(normalize(rootDir))) return null;
+  const root = normalize(rootDir);
+  const target = normalize(join(root, cleaned === '/' ? '' : cleaned));
+  // Containment: target must be rootDir itself or strictly beneath it.
+  // `relative(root, target)` is '' for root itself (accepted) and a descendant
+  // path with no leading '..' for in-root assets. Reject when it climbs out
+  // (exactly '..', or '..' + separator) or — cross-drive on Windows — is
+  // absolute. Guarding on '..' + separator rather than a bare '..' prefix avoids
+  // falsely rejecting legitimate in-root names that merely *begin* with '..'
+  // (e.g. a '..foo' asset), which would re-introduce a looser prefix check.
+  const rel = relative(root, target);
+  if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) return null;
   return target;
 }
 

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { applyUpdate, type NpmExecutor, type NpmResult } from '../apply.js';
+import { applyUpdate, buildNpmSpawnSpec, quoteWindowsArg, type NpmExecutor, type NpmResult } from '../apply.js';
 import { UpdateErrorException } from '../types.js';
 
 function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
@@ -99,3 +99,60 @@ describe('applyUpdate', () => {
     ]);
   });
 });
+
+describe('quoteWindowsArg', () => {
+  it('leaves safe args untouched', () => {
+    expect(quoteWindowsArg('install')).toBe('install');
+    expect(quoteWindowsArg('-g')).toBe('-g');
+    expect(quoteWindowsArg('@serfab/cadre-host@0.7.0')).toBe('@serfab/cadre-host@0.7.0');
+  });
+
+  it('quotes args containing whitespace or shell metachars', () => {
+    expect(quoteWindowsArg('has space')).toBe('"has space"');
+    expect(quoteWindowsArg('with&amp')).toBe('"with&amp"');
+    expect(quoteWindowsArg('pipe|me')).toBe('"pipe|me"');
+  });
+
+  it('escapes embedded quotes and trailing backslashes', () => {
+    expect(quoteWindowsArg('with"quote')).toBe('"with\\"quote"');
+    expect(quoteWindowsArg('trailing\\')).toBe('trailing\\');
+    expect(quoteWindowsArg('trail ing\\')).toBe('"trail ing\\\\"');
+  });
+
+  it('rejects control characters', () => {
+    expect(() => quoteWindowsArg('bad\nnewline')).toThrow(/control character/);
+    expect(() => quoteWindowsArg('bad\x00null')).toThrow(/control character/);
+  });
+});
+
+describe('buildNpmSpawnSpec', () => {
+  it('builds a single-string command with empty args on Windows', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm install -g @serfab/cadre-host@0.7.0',
+        args: [],
+        shell: true,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+
+  it('passes args through verbatim on posix (no shell)', () => {
+    const original = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    try {
+      const spec = buildNpmSpawnSpec(['install', '-g', '@serfab/cadre-host@0.7.0']);
+      expect(spec).toEqual({
+        command: 'npm',
+        args: ['install', '-g', '@serfab/cadre-host@0.7.0'],
+        shell: false,
+      });
+    } finally {
+      Object.defineProperty(process, 'platform', { value: original, configurable: true });
+    }
+  });
+});

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

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { generateKeyPairSync, type KeyObject } from 'node:crypto';
 
-import { canonicalJson, signManifestForTesting, verifyManifest } from '../manifest.js';
+import { canonicalJson, signManifest, verifyManifest } from '../manifest.js';
 import type { UpdateManifest } from '../types.js';
 
 /** Generate a fresh Ed25519 keypair and surface the raw 32-byte public key. */
@@ -47,19 +47,19 @@ describe('verifyManifest', () => {
   });
 
   it('round-trips: sign + verify', () => {
-    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const envelope = signManifest(sampleManifest, kp.privateKey);
     const out = verifyManifest(envelope);
     expect(out).toEqual(sampleManifest);
   });
 
   it('rejects a mutated payload (signature_invalid)', () => {
-    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const envelope = signManifest(sampleManifest, kp.privateKey);
     const tampered = { ...envelope, manifest: { ...envelope.manifest, version: '99.0.0' } };
     expect(() => verifyManifest(tampered)).toThrow(/signature/i);
   });
 
   it('rejects a mutated signature (signature_invalid)', () => {
-    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const envelope = signManifest(sampleManifest, kp.privateKey);
     const sigBytes = Buffer.from(envelope.sig.slice('ed25519:'.length), 'base64');
     sigBytes[0] ^= 0xff;
     const tampered = { ...envelope, sig: `ed25519:${sigBytes.toString('base64')}` };
@@ -67,7 +67,7 @@ describe('verifyManifest', () => {
   });
 
   it('rejects an envelope signed by a different key (signature_invalid)', () => {
-    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const envelope = signManifest(sampleManifest, kp.privateKey);
     // Swap the env-configured public key to a different fresh one.
     const other = freshKeypair();
     process.env.CADRE_HOST_UPDATE_DEV_KEY = other.publicRawB64;
@@ -86,8 +86,43 @@ describe('verifyManifest', () => {
   });
 
   it('rejects unsupported signature schemes', () => {
-    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const envelope = signManifest(sampleManifest, kp.privateKey);
     const tampered = { ...envelope, sig: envelope.sig.replace('ed25519:', 'rsa:') };
     expect(() => verifyManifest(tampered)).toThrow(/unsupported signature scheme/);
   });
+
+  it('rejects non-semver manifest.version (manifest_invalid)', () => {
+    const envelope = signManifest(
+      { ...sampleManifest, version: 'not-a-semver' },
+      kp.privateKey,
+    );
+    expect(() => verifyManifest(envelope)).toThrow(/not a valid semver/i);
+  });
+
+  it('rejects non-semver minPreviousVersion (manifest_invalid)', () => {
+    const envelope = signManifest(
+      { ...sampleManifest, minPreviousVersion: '0.6' },
+      kp.privateKey,
+    );
+    expect(() => verifyManifest(envelope)).toThrow(/minPreviousVersion.*not a valid semver/i);
+  });
+
+  it('rejects publishedAt that is not a round-trippable ISO-8601 string', () => {
+    const envelope = signManifest(
+      { ...sampleManifest, publishedAt: 'sometime last week' },
+      kp.privateKey,
+    );
+    expect(() => verifyManifest(envelope)).toThrow(/publishedAt.*ISO-8601/i);
+  });
+
+  it('rejects an npm package name that fails the naming regex', () => {
+    const envelope = signManifest(
+      {
+        ...sampleManifest,
+        channels: { npm: { package: 'BAD CHARS!', tag: 'latest' } },
+      },
+      kp.privateKey,
+    );
+    expect(() => verifyManifest(envelope)).toThrow(/not a valid npm package name/);
+  });
 });

package/src/update/__tests__/release-key.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { generateKeyPairSync } from 'node:crypto';
+
+import { isPlaceholderReleaseKey } from '../release-key.js';
+
+function freshPublicRawB64(): string {
+  const { publicKey } = generateKeyPairSync('ed25519');
+  const raw = publicKey.export({ format: 'der', type: 'spki' }).subarray(12);
+  return Buffer.from(raw).toString('base64');
+}
+
+describe('isPlaceholderReleaseKey', () => {
+  afterEach(() => { delete process.env.CADRE_HOST_UPDATE_DEV_KEY; });
+
+  it('is true for the default all-zeros placeholder (no override)', () => {
+    delete process.env.CADRE_HOST_UPDATE_DEV_KEY;
+    expect(isPlaceholderReleaseKey()).toBe(true);
+  });
+
+  it('is false when a real key overrides via CADRE_HOST_UPDATE_DEV_KEY', () => {
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = freshPublicRawB64();
+    expect(isPlaceholderReleaseKey()).toBe(false);
+  });
+
+  it('honors an explicit env argument over process.env', () => {
+    expect(isPlaceholderReleaseKey({ CADRE_HOST_UPDATE_DEV_KEY: freshPublicRawB64() })).toBe(false);
+    expect(isPlaceholderReleaseKey({})).toBe(true);
+  });
+});

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);
 }