@serfab/cadre-host 0.7.1 → 0.8.1

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';

package/src/update/manifest.ts

@@ -1,172 +1,214 @@
-/**
- * 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}`);
-}
+/**
+ * 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 (`canonicalJson`) is shared from `@serfab/cadre-core`
+ * so the seed-signing path and this manifest-signing path agree on the signed
+ * byte representation; the shape we sign here is fixed (`UpdateManifest`).
+ */
+
+import { sign as cryptoSign, verify as cryptoVerify, type KeyObject } from 'node:crypto';
+
+import { canonicalJson } from '@serfab/cadre-core';
+
+import { ed25519FromRaw, getReleasePublicKey, getReleasePublicKeyBase64 } from './release-key.js';
+import {
+  UpdateErrorException,
+  type SignedManifest,
+  type UpdateManifest,
+} from './types.js';
+import { parseVersion } from './version.js';
+
+/** npm package naming rule — slightly looser than the official one (we don't enforce length here other than the 214-char total). */
+const NPM_PACKAGE_NAME_RE = /^(?:@[a-z0-9-_.]+\/)?[a-z0-9-_.]+$/;
+
+/** 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');
+  }
+  validateManifestFields(body.manifest);
+
+  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;
+}
+
+/**
+ * Sign a manifest with the release private key, producing the `{ manifest, sig }`
+ * envelope published as `latest.json`. This is the production signing operation:
+ * it canonicalizes with the same `canonicalJson` that `verifyManifest` consumes
+ * and emits a detached `ed25519:<base64>` signature. The private key never ships
+ * in the binary — signing runs offline on the release operator's machine (see
+ * `scripts/sign-manifest.mjs`).
+ */
+export function signManifest(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';
+}
+
+/**
+ * Field-level validation that goes beyond the structural `isUpdateManifest`
+ * type guard: enforces semver on version strings, ISO-8601 round-tripping on
+ * the publish timestamp, and the npm naming regex on the package name. A
+ * signed-but-malformed manifest would otherwise surface as a confusing
+ * `compareVersions` throw further downstream.
+ *
+ * Exported so the offline signing tool (`sign.ts` / `sign-manifest.mjs`) runs
+ * the *exact same* rules before it signs — the signer can never emit a
+ * manifest that `verifyManifest` would later reject as `manifest_invalid`.
+ */
+export function validateManifestFields(m: UpdateManifest): void {
+  try {
+    parseVersion(m.version);
+  } catch (err) {
+    throw new UpdateErrorException(
+      'manifest_invalid',
+      `manifest version "${m.version}" is not a valid semver: ${(err as Error).message}`,
+    );
+  }
+  if (m.minPreviousVersion !== undefined) {
+    try {
+      parseVersion(m.minPreviousVersion);
+    } catch (err) {
+      throw new UpdateErrorException(
+        'manifest_invalid',
+        `manifest minPreviousVersion "${m.minPreviousVersion}" is not a valid semver: ${(err as Error).message}`,
+      );
+    }
+  }
+  const parsed = new Date(m.publishedAt);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== m.publishedAt) {
+    throw new UpdateErrorException(
+      'manifest_invalid',
+      `manifest publishedAt "${m.publishedAt}" is not a round-trippable ISO-8601 string`,
+    );
+  }
+  const pkg = m.channels.npm.package;
+  if (!NPM_PACKAGE_NAME_RE.test(pkg) || pkg.length > 214) {
+    throw new UpdateErrorException(
+      'manifest_invalid',
+      `manifest channels.npm.package "${pkg}" is not a valid npm package name`,
+    );
+  }
+}
+
+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 serializer used to define the signed byte representation.
+ * The implementation lives in `@serfab/cadre-core` (cadre-host depends on
+ * cadre-core); re-exported here so existing import sites stay stable.
+ */
+export { canonicalJson } from '@serfab/cadre-core';

package/src/update/release-key.ts

@@ -2,27 +2,23 @@
  * Production Ed25519 public key used to verify the update manifest.
  *
  * The signing key lives offline with the release operator; only the public
- * half ever ships in the binary.
- *
- * **Provisional key.** The placeholder below is regenerated whenever the
- * release tooling is rotated — the key in this file is replaced atomically
- * by the release build. CI keys differ from prod keys; for dev/CI overrides
- * see `CADRE_HOST_UPDATE_DEV_KEY`.
+ * half ever ships in the binary. The release operator generates the keypair
+ * and embeds the public half with `scripts/release-keygen.mjs --write-source`;
+ * see the "Release signing & key management" runbook in `docs/cadre-host.md`.
+ * For dev/CI/staging overrides see `CADRE_HOST_UPDATE_DEV_KEY`.
  */
 
-import { createPublicKey, KeyObject } from 'node:crypto';
+import type { KeyObject } from 'node:crypto';
+import { createPublicKey } from 'node:crypto';
 
 /**
- * Raw 32-byte Ed25519 public key, base64-encoded. Placeholder pending key
- * generation by the release op. Mismatch with the real signer will surface
- * as `signature_invalid`, which the UI treats as "update available but
- * unverifiable" rather than auto-applying.
- *
- * The real key generation/publication procedure is tracked in the
- * release-tooling backlog; until then, the dev override below is the only
- * supported path for CI + local manifest testing.
+ * Raw 32-byte Ed25519 public key, base64-encoded. The all-zeros value below is
+ * the placeholder that ships in source until the release operator embeds a real
+ * key (`isPlaceholderReleaseKey` reports it; the publish guard refuses to ship
+ * it). Mismatch with the real signer surfaces as `signature_invalid`, which the
+ * UI treats as "update available but unverifiable" rather than auto-applying.
  */
-const PROD_KEY_BASE64 = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+const PROD_KEY_BASE64 = 'XyRVnOY9DVgU6xdMgJIguOsc9B2L1o2KoU9626Nk+OE=';
 
 /**
  * Public key (32 raw bytes, base64) — env override beats the embedded one.
@@ -39,6 +35,24 @@ export function getReleasePublicKey(env: NodeJS.ProcessEnv = process.env): KeyOb
   return ed25519FromRaw(getReleasePublicKeyBase64(env));
 }
 
+/**
+ * True when the *effective* release key (after the `CADRE_HOST_UPDATE_DEV_KEY`
+ * override) decodes to 32 zero bytes — i.e. the all-zeros placeholder that
+ * ships in source until the release operator embeds a real public key.
+ *
+ * Consumers:
+ *  - the publish guard (`scripts/publish-package.js`) refuses to ship a build
+ *    whose embedded key is still the placeholder, so a real release can never
+ *    silently ship the dead key;
+ *  - `UpdateService.check()` logs a diagnostic breadcrumb so a misbuilt binary
+ *    is recognizable from logs rather than only as opaque `signature_invalid`.
+ */
+export function isPlaceholderReleaseKey(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = Buffer.from(getReleasePublicKeyBase64(env), 'base64');
+  if (raw.length !== 32) return false;
+  return raw.every((b) => b === 0);
+}
+
 /**
  * Build an Ed25519 KeyObject from a raw 32-byte base64 public key by wrapping
  * it in the SubjectPublicKeyInfo DER prefix Node expects.

package/src/update/sign.ts

@@ -0,0 +1,74 @@
+/**
+ * Typed signing core for the release-manifest pipeline.
+ *
+ * The offline `.mjs` CLI wrappers (`scripts/sign-manifest.mjs`) stay thin by
+ * delegating manifest construction, field validation, and the sign + self-verify
+ * round-trip to this module — keeping the logic typed and unit-testable instead
+ * of hand-rolled in a script. None of this ships in the running binary's hot
+ * path: it is only reached by the operator's offline signing tool (and tests).
+ */
+
+import { createPublicKey, type KeyObject } from 'node:crypto';
+
+import { signManifest, validateManifestFields, verifyManifest } from './manifest.js';
+import type { SignedManifest, UpdateManifest } from './types.js';
+
+/** Flat input shape the signing CLI collects from flags or a JSON file. */
+export interface ManifestFields {
+  /** Released version (semver). */
+  version: string;
+  /** npm package the release publishes under. */
+  package: string;
+  /** npm dist-tag (e.g. `latest`). */
+  tag: string;
+  /** ISO-8601 publish timestamp (must round-trip exactly). */
+  publishedAt: string;
+  /** Optional human-facing release-notes URL. */
+  releaseNotesUrl?: string;
+  /** Optional minimum previous version that can step directly to this release. */
+  minPreviousVersion?: string;
+}
+
+/**
+ * Construct a well-formed `UpdateManifest` from flat fields and run the exact
+ * `validateManifestFields` rules `verifyManifest` will later apply — so the
+ * signing tool fails loudly on a bad semver / npm name / non-ISO timestamp
+ * rather than emitting a manifest the verifier would reject as `manifest_invalid`.
+ */
+export function buildManifest(fields: ManifestFields): UpdateManifest {
+  const manifest: UpdateManifest = {
+    v: 1,
+    version: fields.version,
+    publishedAt: fields.publishedAt,
+    channels: { npm: { package: fields.package, tag: fields.tag } },
+    ...(fields.releaseNotesUrl !== undefined ? { releaseNotesUrl: fields.releaseNotesUrl } : {}),
+    ...(fields.minPreviousVersion !== undefined ? { minPreviousVersion: fields.minPreviousVersion } : {}),
+  };
+  validateManifestFields(manifest);
+  return manifest;
+}
+
+/**
+ * Derive the raw 32-byte Ed25519 public key (base64) from a private key by
+ * stripping the 12-byte SPKI DER header — the same form `release-key.ts`
+ * embeds and `ed25519FromRaw` consumes.
+ */
+export function derivePublicKeyBase64(privateKey: KeyObject): string {
+  const spki = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+  return Buffer.from(spki.subarray(12)).toString('base64');
+}
+
+/**
+ * Sign a manifest and immediately verify the result against the public key
+ * *derived from the same private key*, independent of whatever key the running
+ * environment trusts. Throws if the self-check fails, so the signing tool never
+ * emits an envelope it could not itself verify.
+ */
+export function signAndSelfVerify(manifest: UpdateManifest, privateKey: KeyObject): SignedManifest {
+  const signed = signManifest(manifest, privateKey);
+  const publicRawB64 = derivePublicKeyBase64(privateKey);
+  // verifyManifest honors the env override; point it at the derived key only so
+  // the self-check is against this key pair, not the embedded/dev key.
+  verifyManifest(signed, { CADRE_HOST_UPDATE_DEV_KEY: publicRawB64 } as NodeJS.ProcessEnv);
+  return signed;
+}