@serfab/cadre-host 0.7.1 → 0.9.0

package/src/server/routes/grants.ts

@@ -0,0 +1,186 @@
+/**
+ * Grantee-facing donation routes — the HTTP surface an external cadre authority
+ * (a friend's phone) drives to have this host donate a node into *its* cadre.
+ *
+ * Mount path: `/grants`. Distinct from the loopback-only `/grants-admin` surface
+ * (issue/list/revoke, no bearer): this one is **bearer-gated** — every request
+ * carries `Authorization: Bearer <grant-token>`, and a grantee sees only the
+ * donations its own grant authorized (the single cross-grantee boundary,
+ * analogous to cadre-provider's per-customer ownership check).
+ *
+ * Reachability is out of scope here: in v1 this mounts on the loopback
+ * management server, same as the trust-circle / NAT surfaces. Physically exposing
+ * it to a remote phone is `backlog/feat-cadre-host-wan-grant-reachability`.
+ *
+ * Errors: handlers either send a `{ ok:false, error:{code,message} }` envelope
+ * inline (auth / body validation) or let the `DonationService` throw a
+ * `DonationError`, which `server/error-handler.ts` maps to the matching HTTP
+ * status and the same envelope.
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+
+import type { DonationService, DonationProvisionRequest } from '../../donation/donation-service.js';
+import type { DonationView, GrantValidator } from '../../donation/types.js';
+
+export interface GrantsRoutesOptions {
+  donations: DonationService;
+  /** Validates the presented bearer for non-provisioning ops (provision revalidates internally). */
+  grants: GrantValidator;
+}
+
+/** Uniform error envelope (matches `error-handler.ts` and the provider API). */
+function errorResponse(reply: FastifyReply, code: string, message: string, status: number) {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+/** Pull the `Bearer <token>` value out of the Authorization header, or undefined. */
+function parseBearer(header: string | undefined): string | undefined {
+  if (!header) return undefined;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : undefined;
+}
+
+/** Map a grant denial reason to an HTTP status for the bearer gate. */
+function denyStatus(reason: string | undefined): number {
+  if (reason === 'expired' || reason === 'revoked') return 403;
+  return 401; // unknown_token / missing
+}
+
+/**
+ * Authenticate the grant bearer for a non-provisioning op (identity + not
+ * expired/revoked; no quota). Returns the token, or null after sending the
+ * failure response. Provision does its own quota-aware validation inside
+ * `DonationService.provision`.
+ */
+function authenticate(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  grants: GrantValidator,
+): string | null {
+  const token = parseBearer(request.headers.authorization);
+  if (!token) {
+    errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    return null;
+  }
+  const validation = grants.validate(token);
+  if (!validation.ok) {
+    const status = denyStatus(validation.reason);
+    // Keep the envelope code aligned with the status (and with the POST path,
+    // which surfaces an unknown token as `unauthorized`): 401 → unauthorized,
+    // 403 → forbidden. A 401 labelled `forbidden` is self-contradictory.
+    const code = status === 403 ? 'forbidden' : 'unauthorized';
+    errorResponse(reply, code, `Grant is ${validation.reason ?? 'invalid'}`, status);
+    return null;
+  }
+  return token;
+}
+
+/**
+ * Resolve a donation the presented grant owns. Returns the redacted view, or
+ * null after sending a 404 — an unknown id and one owned by a *different* grant
+ * are deliberately indistinguishable (a grantee never learns another grantee's
+ * donations exist).
+ */
+function requireOwned(
+  donations: DonationService,
+  id: string,
+  token: string,
+  reply: FastifyReply,
+): DonationView | null {
+  const donation = donations.get(id);
+  if (!donation || donation.grantToken !== token) {
+    errorResponse(reply, 'not_found', `No such donation: ${id}`, 404);
+    return null;
+  }
+  return donation;
+}
+
+export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOptions): void {
+  const { donations, grants } = opts;
+
+  // POST /grants — provision a donated node. The bearer's identity/expiry/
+  // revocation AND quota are validated inside provision(), which throws a
+  // DonationError (unauthorized / forbidden / quota_exceeded) the error handler
+  // maps. We only parse the bearer and validate the request body here.
+  app.post('/grants', async (request, reply) => {
+    const token = parseBearer(request.headers.authorization);
+    if (!token) {
+      return errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    }
+
+    const body = (request.body ?? {}) as Partial<DonationProvisionRequest>;
+    if (typeof body.partyId !== 'string' || body.partyId.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'partyId is required', 400);
+    }
+    if (!Array.isArray(body.bootstrapNodes) || body.bootstrapNodes.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'bootstrapNodes is required', 400);
+    }
+    if (!Array.isArray(body.ownerKeys) || body.ownerKeys.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'ownerKeys is required', 400);
+    }
+    if (body.profile !== undefined && body.profile !== 'storage' && body.profile !== 'transaction') {
+      return errorResponse(reply, 'invalid_request', 'profile must be "storage" or "transaction"', 400);
+    }
+
+    const donation = await donations.provision({
+      grantToken: token,
+      partyId: body.partyId,
+      bootstrapNodes: body.bootstrapNodes,
+      ownerKeys: body.ownerKeys,
+      ...(body.profile ? { profile: body.profile } : {}),
+    });
+    return reply.status(201).send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants — list only the donations this grant authorized.
+  app.get('/grants', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    return reply.send({ ok: true, data: { donations: donations.list(token) } });
+  });
+
+  // GET /grants/:id — one donation (redacted), owned by this grant.
+  app.get<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    const donation = requireOwned(donations, request.params.id, token, reply);
+    if (!donation) return reply;
+    return reply.send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants/:id/peer — live { peerId, multiaddrs } for the requester's addDrone.
+  app.get<{ Params: { id: string } }>('/grants/:id/peer', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    const peer = await donations.getPeer(request.params.id);
+    return reply.send({ ok: true, data: peer });
+  });
+
+  // PUT /grants/:id/seed — apply the requester's phone-signed seed.
+  app.put<{ Params: { id: string } }>('/grants/:id/seed', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+
+    const body = (request.body ?? {}) as { seed?: unknown };
+    if (typeof body.seed !== 'string' || body.seed.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'seed is required', 400);
+    }
+    const result = await donations.applySeed(request.params.id, body.seed);
+    if (!result.success) {
+      return errorResponse(reply, 'seed_failed', result.error ?? 'Node rejected the seed', 502);
+    }
+    return reply.send({ ok: true, data: { peersAdded: result.peersAdded ?? 0 } });
+  });
+
+  // DELETE /grants/:id — terminate the donated node.
+  app.delete<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    await donations.terminate(request.params.id);
+    return reply.send({ ok: true });
+  });
+}

package/src/server/routes/nodes.ts

@@ -6,9 +6,11 @@
  * `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 owner node (re-spawned from the
+ * persisted `OwnerSpawnConfig`). Generic node lifecycle is owned by the
+ * grantee-facing donation surface (`/grants`) — this route no longer spawns
+ * generic nodes; start/restart of a known non-owner node points the caller
+ * there. Stop works for any running node.
  */
 
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
@@ -82,35 +84,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 owner node (spawned from the
+  // persisted OwnerSpawnConfig). Generic node lifecycle now belongs to the
+  // donation surface (/grants) — those ids return a clear not_implemented that
+  // points there; 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.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `start ${id}: owner node has no saved spawn config.`);
+      }
+      const node = await orchestrator.ensureOwnerNode();
+      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.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `restart ${id}: owner node has no saved spawn config.`);
+      }
+      const node = await orchestrator.restartOwnerNode();
+      return { ok: true, data: { node } };
+    }
+    return startRestartFallback(reply, orchestrator, id, 'restart');
+  });
+}
+
+/** 404 for unknown ids; 501 not_implemented for known non-owner 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 owner node is start/restart-able here; generic donated-node lifecycle is owned by the donation surface — use POST /grants to provision and DELETE /grants/:id to terminate.`,
+  );
+}
+
+function notImplemented(reply: import('fastify').FastifyReply, message: string) {
+  return reply.code(501).send({ ok: false, error: { code: 'not_implemented', message } });
 }
 
 /**

package/src/server/routes/settings.ts

@@ -21,14 +21,19 @@ import type { NatService } from '../../nat/index.js';
 import type { UpdateService } from '../../update/index.js';
 import type { HostSettingsStore } from '../settings-store.js';
 
-const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version']);
+const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version', 'ownCadre']);
 
 const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
 const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
 
 export interface SettingsRoutesOptions {
   settingsStore: HostSettingsStore;
-  nat: NatService;
+  /**
+   * Present only when the host runs its own personal cadre. In donor-only mode
+   * an `upnpEnabled` write still persists to host.config.json but has no running
+   * NatService to propagate into.
+   */
+  nat?: NatService;
   update?: UpdateService;
 }
 
@@ -58,7 +63,10 @@ export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoute
       // takes effect immediately. NatService persists into nat.json — that's
       // independent of host.config.json's `upnpEnabled` (which the installer
       // uses on first run to seed nat.json). Update both for consistency.
-      await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      // In donor-only mode there is no NatService — the write still persists.
+      if (nat) {
+        await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      }
     }
     if ('updates' in body) {
       const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };

package/src/server/routes/status.ts

@@ -22,8 +22,10 @@ const PROCESS_STARTED_AT = process.hrtime.bigint();
 
 export interface StatusRouteOptions {
   orchestrator: HostProcessOrchestrator;
-  trustCircle: TrustCircleService;
-  nat: NatService;
+  /** Present only when the host runs its own personal cadre (`ownCadre.enabled`). */
+  trustCircle?: TrustCircleService;
+  /** Present only when the host runs its own personal cadre (`ownCadre.enabled`). */
+  nat?: NatService;
   update?: UpdateService;
 }
 
@@ -35,8 +37,10 @@ export interface StatusResponse {
     status: ManagedNodeInfo['status'];
     profile: ManagedNodeInfo['profile'];
   }>;
-  trustCircle: { members: number; pending: number };
-  connectivity: NatStatusSnapshot;
+  /** Omitted in donor-only mode (no host-own trust circle). */
+  trustCircle?: { members: number; pending: number };
+  /** Omitted in donor-only mode (no NAT service). */
+  connectivity?: NatStatusSnapshot;
   update?: { available?: string; lastChecked?: string };
 }
 
@@ -50,8 +54,6 @@ export function registerStatusRoute(app: FastifyInstance, opts: StatusRouteOptio
       status: n.status,
       profile: n.profile,
     }));
-    const tc = await opts.trustCircle.list();
-    const connectivity = opts.nat.getStatus();
 
     const response: StatusResponse = {
       service: {
@@ -60,10 +62,18 @@ export function registerStatusRoute(app: FastifyInstance, opts: StatusRouteOptio
         uptimeSeconds: secondsSince(PROCESS_STARTED_AT),
       },
       nodes,
-      trustCircle: { members: tc.members.length, pending: tc.pending.length },
-      connectivity,
     };
 
+    // Trust-circle + connectivity exist only when the host runs its own
+    // personal cadre; donor-only mode omits both.
+    if (opts.trustCircle) {
+      const tc = await opts.trustCircle.list();
+      response.trustCircle = { members: tc.members.length, pending: tc.pending.length };
+    }
+    if (opts.nat) {
+      response.connectivity = opts.nat.getStatus();
+    }
+
     if (opts.update) {
       const state = await opts.update.getState();
       const update: { available?: string; lastChecked?: string } = {};

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,42 @@
+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 an explicit all-zeros placeholder key', () => {
+    const allZeros = Buffer.alloc(32).toString('base64');
+    expect(isPlaceholderReleaseKey({ CADRE_HOST_UPDATE_DEV_KEY: allZeros })).toBe(true);
+  });
+
+  it('is false for the shipped embedded default (real key, no override)', () => {
+    delete process.env.CADRE_HOST_UPDATE_DEV_KEY;
+    expect(isPlaceholderReleaseKey()).toBe(false);
+  });
+
+  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);
+    // no override in the explicit arg -> falls through to the real embedded default
+    expect(isPlaceholderReleaseKey({})).toBe(false);
+  });
+
+  it('is false for a key that does not decode to 32 bytes', () => {
+    // Not the all-zeros placeholder even though it is a degenerate key: the
+    // 32-byte length gate short-circuits before the all-zeros check.
+    const shortZeros = Buffer.alloc(16).toString('base64');
+    expect(isPlaceholderReleaseKey({ CADRE_HOST_UPDATE_DEV_KEY: shortZeros })).toBe(false);
+  });
+});