@serfab/cadre-host 0.9.0 → 0.11.0

package/src/update/release-key.ts

@@ -1,71 +1,71 @@
-/**
- * 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. 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 type { KeyObject } from 'node:crypto';
-import { createPublicKey } from 'node:crypto';
-
-/**
- * Raw 32-byte Ed25519 public key, base64-encoded. This is the real production
- * public key embedded by the release operator (see the "Release signing"
- * runbook in `docs/cadre-host.md`). Before a real key was embedded the source
- * shipped an all-zeros placeholder; `isPlaceholderReleaseKey` still detects that
- * state and 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 = 'XyRVnOY9DVgU6xdMgJIguOsc9B2L1o2KoU9626Nk+OE=';
-
-/**
- * Public key (32 raw bytes, base64) — env override beats the embedded one.
- * Used by both production and CI smoke tests.
- */
-export function getReleasePublicKeyBase64(env: NodeJS.ProcessEnv = process.env): string {
-  const override = env.CADRE_HOST_UPDATE_DEV_KEY?.trim();
-  if (override && override.length > 0) return override;
-  return PROD_KEY_BASE64;
-}
-
-/** Lazily build the KeyObject used by `crypto.verify`. */
-export function getReleasePublicKey(env: NodeJS.ProcessEnv = process.env): KeyObject {
-  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.
- */
-export function ed25519FromRaw(base64Raw: string): KeyObject {
-  const raw = Buffer.from(base64Raw, 'base64');
-  if (raw.length !== 32) {
-    throw new Error(`Ed25519 public key must be 32 bytes, got ${raw.length}`);
-  }
-  // SPKI DER prefix for Ed25519: 0x302a300506032b6570032100
-  const prefix = Buffer.from('302a300506032b6570032100', 'hex');
-  const spki = Buffer.concat([prefix, raw]);
-  return createPublicKey({ key: spki, format: 'der', type: 'spki' });
-}
+/**
+ * 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. 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 type { KeyObject } from 'node:crypto';
+import { createPublicKey } from 'node:crypto';
+
+/**
+ * Raw 32-byte Ed25519 public key, base64-encoded. This is the real production
+ * public key embedded by the release operator (see the "Release signing"
+ * runbook in `docs/cadre-host.md`). Before a real key was embedded the source
+ * shipped an all-zeros placeholder; `isPlaceholderReleaseKey` still detects that
+ * state and 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 = 'XyRVnOY9DVgU6xdMgJIguOsc9B2L1o2KoU9626Nk+OE=';
+
+/**
+ * Public key (32 raw bytes, base64) — env override beats the embedded one.
+ * Used by both production and CI smoke tests.
+ */
+export function getReleasePublicKeyBase64(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.CADRE_HOST_UPDATE_DEV_KEY?.trim();
+  if (override && override.length > 0) return override;
+  return PROD_KEY_BASE64;
+}
+
+/** Lazily build the KeyObject used by `crypto.verify`. */
+export function getReleasePublicKey(env: NodeJS.ProcessEnv = process.env): KeyObject {
+  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.mjs`) 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.
+ */
+export function ed25519FromRaw(base64Raw: string): KeyObject {
+  const raw = Buffer.from(base64Raw, 'base64');
+  if (raw.length !== 32) {
+    throw new Error(`Ed25519 public key must be 32 bytes, got ${raw.length}`);
+  }
+  // SPKI DER prefix for Ed25519: 0x302a300506032b6570032100
+  const prefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const spki = Buffer.concat([prefix, raw]);
+  return createPublicKey({ key: spki, format: 'der', type: 'spki' });
+}

package/src/update/sign.ts

@@ -1,74 +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;
-}
+/**
+ * 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;
+}

package/src/update/store.ts

@@ -1,101 +1,101 @@
-/**
- * Atomic JSON store for `<dataDir>/update-state.json`.
- *
- * Mirrors `TrustCircleStore` / `NatStore`: load on demand, write to
- * `<path>.tmp` then rename. Single-writer assumption — only one cadre-host
- * process owns a given dataDir.
- */
-
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import debug from 'debug';
-
-import { UpdateErrorException, type UpdateState } from './types.js';
-
-const log = debug('cadre:host:update-store');
-
-const FILE_VERSION = 1;
-const FILE_NAME = 'update-state.json';
-
-export class UpdateStateStore {
-  private readonly path: string;
-  private cache: UpdateState | null = null;
-
-  constructor(rootDir: string) {
-    mkdirSync(rootDir, { recursive: true });
-    this.path = join(rootDir, FILE_NAME);
-  }
-
-  filePath(): string {
-    return this.path;
-  }
-
-  /** Load (with caching). A missing file returns an empty state. */
-  load(): UpdateState {
-    if (this.cache) return this.cache;
-    if (!existsSync(this.path)) {
-      this.cache = { version: FILE_VERSION };
-      return this.cache;
-    }
-    let raw: string;
-    try {
-      raw = readFileSync(this.path, 'utf8');
-    } catch (err) {
-      throw new UpdateErrorException(
-        'storage_error',
-        `failed to read update-state at ${this.path}: ${(err as Error).message}`,
-      );
-    }
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      throw new UpdateErrorException(
-        'storage_error',
-        `update-state at ${this.path} is not valid JSON: ${(err as Error).message}`,
-      );
-    }
-    if (!parsed || typeof parsed !== 'object') {
-      throw new UpdateErrorException('storage_error', `update-state at ${this.path} is not an object`);
-    }
-    const obj = parsed as Record<string, unknown>;
-    if (obj.version !== FILE_VERSION) {
-      throw new UpdateErrorException(
-        'unsupported_state_version',
-        `update-state at ${this.path} has unsupported version ${String(obj.version)}`,
-      );
-    }
-    this.cache = obj as unknown as UpdateState;
-    return this.cache;
-  }
-
-  /** Persist a new state atomically. */
-  save(state: UpdateState): void {
-    const next: UpdateState = { ...state, version: FILE_VERSION };
-    const payload = JSON.stringify(next, null, 2) + '\n';
-    const tmp = `${this.path}.tmp`;
-    writeFileSync(tmp, payload, { encoding: 'utf8' });
-    renameSync(tmp, this.path);
-    this.cache = next;
-    log('saved update-state.json (available=%s, applying=%s) to %s',
-      next.available?.version ?? '-',
-      next.applyInProgress ? `${next.applyInProgress.fromVersion}→${next.applyInProgress.toVersion}` : '-',
-      this.path);
-  }
-
-  /** Merge a patch into the current state and persist. */
-  update(patch: Partial<Omit<UpdateState, 'version'>>): UpdateState {
-    const current = this.load();
-    const next: UpdateState = { ...current, ...patch, version: FILE_VERSION };
-    this.save(next);
-    return next;
-  }
-
-  /** Drop a specific field from the persisted state. */
-  clearField<K extends keyof Omit<UpdateState, 'version'>>(field: K): UpdateState {
-    const current = { ...this.load() };
-    delete current[field];
-    this.save(current);
-    return current;
-  }
-}
+/**
+ * Atomic JSON store for `<dataDir>/update-state.json`.
+ *
+ * Mirrors `TrustCircleStore` / `NatStore`: load on demand, write to
+ * `<path>.tmp` then rename. Single-writer assumption — only one cadre-host
+ * process owns a given dataDir.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import debug from 'debug';
+
+import { UpdateErrorException, type UpdateState } from './types.js';
+
+const log = debug('cadre:host:update-store');
+
+const FILE_VERSION = 1;
+const FILE_NAME = 'update-state.json';
+
+export class UpdateStateStore {
+  private readonly path: string;
+  private cache: UpdateState | null = null;
+
+  constructor(rootDir: string) {
+    mkdirSync(rootDir, { recursive: true });
+    this.path = join(rootDir, FILE_NAME);
+  }
+
+  filePath(): string {
+    return this.path;
+  }
+
+  /** Load (with caching). A missing file returns an empty state. */
+  load(): UpdateState {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.path)) {
+      this.cache = { version: FILE_VERSION };
+      return this.cache;
+    }
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, 'utf8');
+    } catch (err) {
+      throw new UpdateErrorException(
+        'storage_error',
+        `failed to read update-state at ${this.path}: ${(err as Error).message}`,
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new UpdateErrorException(
+        'storage_error',
+        `update-state at ${this.path} is not valid JSON: ${(err as Error).message}`,
+      );
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      throw new UpdateErrorException('storage_error', `update-state at ${this.path} is not an object`);
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (obj.version !== FILE_VERSION) {
+      throw new UpdateErrorException(
+        'unsupported_state_version',
+        `update-state at ${this.path} has unsupported version ${String(obj.version)}`,
+      );
+    }
+    this.cache = obj as unknown as UpdateState;
+    return this.cache;
+  }
+
+  /** Persist a new state atomically. */
+  save(state: UpdateState): void {
+    const next: UpdateState = { ...state, version: FILE_VERSION };
+    const payload = JSON.stringify(next, null, 2) + '\n';
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, payload, { encoding: 'utf8' });
+    renameSync(tmp, this.path);
+    this.cache = next;
+    log('saved update-state.json (available=%s, applying=%s) to %s',
+      next.available?.version ?? '-',
+      next.applyInProgress ? `${next.applyInProgress.fromVersion}→${next.applyInProgress.toVersion}` : '-',
+      this.path);
+  }
+
+  /** Merge a patch into the current state and persist. */
+  update(patch: Partial<Omit<UpdateState, 'version'>>): UpdateState {
+    const current = this.load();
+    const next: UpdateState = { ...current, ...patch, version: FILE_VERSION };
+    this.save(next);
+    return next;
+  }
+
+  /** Drop a specific field from the persisted state. */
+  clearField<K extends keyof Omit<UpdateState, 'version'>>(field: K): UpdateState {
+    const current = { ...this.load() };
+    delete current[field];
+    this.save(current);
+    return current;
+  }
+}