@serfab/cadre-host 0.7.1

package/dist/ui/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <title>cadre-host</title>
+    <script type="module" crossorigin src="./assets/index-C9uChk2P.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BwU5mJGF.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/dist/update/apply.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Apply an update.
+ *
+ * Apply == reinstall the package globally via `npm install -g <pkg>@<ver>`.
+ * Rollback == reinstall the previously-recorded version. Both are dispatched
+ * through an injectable `NpmExecutor` so tests don't shell out.
+ *
+ * Service-host restart is best-effort: the binary swap succeeded even if
+ * `systemctl/launchctl/nssm restart` returned non-zero, so the state stays
+ * successful and the caller surfaces a warning. (User can restart by hand.)
+ */
+import { type UpdateApplyResult } from './types.js';
+export interface NpmResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** Pluggable npm runner — replaced in tests. */
+export type NpmExecutor = (args: string[]) => Promise<NpmResult>;
+/** Optional service-host restart hook. Returns undefined on success, an error message on failure. */
+export type ServiceRestarter = () => Promise<string | undefined>;
+export interface ApplyOptions {
+    npmPackage: string;
+    fromVersion: string;
+    toVersion: string;
+    npmExecutor?: NpmExecutor;
+    restart?: ServiceRestarter;
+    timeoutMs?: number;
+}
+/**
+ * Drive the install + restart. Throws `UpdateErrorException('apply_failed')`
+ * if the install itself fails (after attempting rollback). On install
+ * success but restart failure, returns a result with the restart error set.
+ */
+export declare function applyUpdate(opts: ApplyOptions): Promise<UpdateApplyResult>;
+/** Default executor: spawn `npm` with the given args. Adds a hard timeout. */
+export declare function defaultNpmExecutor(timeoutMs: number): NpmExecutor;

package/dist/update/apply.js

@@ -0,0 +1,102 @@
+/**
+ * Apply an update.
+ *
+ * Apply == reinstall the package globally via `npm install -g <pkg>@<ver>`.
+ * Rollback == reinstall the previously-recorded version. Both are dispatched
+ * through an injectable `NpmExecutor` so tests don't shell out.
+ *
+ * Service-host restart is best-effort: the binary swap succeeded even if
+ * `systemctl/launchctl/nssm restart` returned non-zero, so the state stays
+ * successful and the caller surfaces a warning. (User can restart by hand.)
+ */
+import { spawn } from 'node:child_process';
+import debug from 'debug';
+import { UpdateErrorException, } from './types.js';
+const log = debug('cadre:host:update-apply');
+const DEFAULT_NPM_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Drive the install + restart. Throws `UpdateErrorException('apply_failed')`
+ * if the install itself fails (after attempting rollback). On install
+ * success but restart failure, returns a result with the restart error set.
+ */
+export async function applyUpdate(opts) {
+    const executor = opts.npmExecutor ?? defaultNpmExecutor(opts.timeoutMs ?? DEFAULT_NPM_TIMEOUT_MS);
+    const installArgs = ['install', '-g', `${opts.npmPackage}@${opts.toVersion}`];
+    let installResult;
+    try {
+        installResult = await executor(installArgs);
+    }
+    catch (err) {
+        await tryRollback(opts.npmPackage, opts.fromVersion, executor);
+        throw new UpdateErrorException('apply_failed', `npm install threw: ${err.message}`);
+    }
+    if (installResult.exitCode !== 0) {
+        const stderrTail = tail(installResult.stderr || installResult.stdout, 400);
+        const rollbackErr = await tryRollback(opts.npmPackage, opts.fromVersion, executor);
+        if (rollbackErr) {
+            throw new UpdateErrorException('rollback_failed', `npm install failed (exit ${installResult.exitCode}); rollback also failed: ${rollbackErr}. Original error: ${stderrTail}`);
+        }
+        throw new UpdateErrorException('apply_failed', `npm install failed (exit ${installResult.exitCode}): ${stderrTail}`);
+    }
+    log('npm install -g %s@%s succeeded', opts.npmPackage, opts.toVersion);
+    let restartError;
+    if (opts.restart) {
+        try {
+            restartError = await opts.restart();
+        }
+        catch (err) {
+            restartError = err.message;
+        }
+        if (restartError) {
+            log('service restart failed: %s', restartError);
+        }
+    }
+    return {
+        fromVersion: opts.fromVersion,
+        toVersion: opts.toVersion,
+        restarted: opts.restart !== undefined && restartError === undefined,
+        ...(restartError ? { restartError } : {}),
+    };
+}
+/** Best-effort rollback. Returns an error string if the rollback itself failed. */
+async function tryRollback(pkg, fromVersion, executor) {
+    log('rolling back to %s@%s', pkg, fromVersion);
+    try {
+        const rollback = await executor(['install', '-g', `${pkg}@${fromVersion}`]);
+        if (rollback.exitCode !== 0) {
+            return `npm install exit ${rollback.exitCode}: ${tail(rollback.stderr || rollback.stdout, 400)}`;
+        }
+        return undefined;
+    }
+    catch (err) {
+        return `npm install threw: ${err.message}`;
+    }
+}
+/** Default executor: spawn `npm` with the given args. Adds a hard timeout. */
+export function defaultNpmExecutor(timeoutMs) {
+    return (args) => new Promise((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 });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+        child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+        const timer = setTimeout(() => {
+            stderr += `\n[cadre-host] npm install timed out after ${timeoutMs}ms, killing`;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolveExec({ exitCode: 127, stdout, stderr: stderr + `\nspawn failed: ${err.message}` });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolveExec({ exitCode: code ?? -1, stdout, stderr });
+        });
+    });
+}
+function tail(s, n) {
+    return s.length <= n ? s : '…' + s.slice(-n);
+}
+//# sourceMappingURL=apply.js.map

package/dist/update/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/update/apply.ts"],"names":[],"mappings":"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"}

package/dist/update/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * UpdateService — the composition root for the cadre-host update flow.
+ *
+ * Background check cadence: once at construction time (`check()` called
+ * explicitly by `cadre-host start` after the management API binds) and a
+ * 24-hour interval timer thereafter. Failures are silent — UI consumers see
+ * `lastChecked` only when a fetch succeeds.
+ *
+ * Apply flow: re-fetch + re-verify the manifest (never trust the cached
+ * `available`), record `applyInProgress`, run `npm install -g`, restart the
+ * service via the optional `ServiceRestarter`, and roll back on failure.
+ */
+import { type NpmExecutor, type ServiceRestarter } from './apply.js';
+import { type UpdateApplyResult, type UpdateSettings, type UpdateState } from './types.js';
+export interface UpdateServiceOptions {
+    /** cadre-host data directory; UpdateState file lives here. */
+    dataDir: string;
+    /** Currently-running package version (from package.json). */
+    currentVersion: string;
+    /** Manifest URL. Defaults: env CADRE_HOST_UPDATE_MANIFEST_URL → DEFAULT_MANIFEST_URL. */
+    manifestUrl?: string;
+    /** Fetcher (test injection). */
+    fetcher?: typeof fetch;
+    /** npm runner (test injection). */
+    npmExecutor?: NpmExecutor;
+    /** Service-host restart hook (test injection / wiring from cadre-host start). */
+    restart?: ServiceRestarter;
+    /** Initial settings (autoApply etc) — typically sourced from host.config.json. */
+    settings?: UpdateSettings;
+    /** Periodic-check interval; defaults to 24h. */
+    checkIntervalMs?: number;
+    /** npm install timeout; defaults to 5m. */
+    npmTimeoutMs?: number;
+}
+/** Handlers for the management-API listener. */
+export interface UpdateHandlers {
+    getState(): Promise<UpdateState>;
+    postApply(): Promise<UpdateApplyResult>;
+    getSettings(): Promise<UpdateSettings>;
+    putSettings(body: {
+        autoApply?: boolean;
+        manifestUrl?: string;
+    }): Promise<UpdateSettings>;
+}
+export declare class UpdateService {
+    private readonly store;
+    private readonly currentVersion;
+    private readonly fetcher;
+    private readonly npmExecutor;
+    private readonly restart;
+    private readonly checkIntervalMs;
+    private readonly npmTimeoutMs;
+    private manifestUrl;
+    private settings;
+    private timer;
+    private applying;
+    /** Persisted settings changes are bubbled out via this callback (wired in cadre-host start). */
+    private onSettingsChange?;
+    constructor(opts: UpdateServiceOptions);
+    /** Read the persisted state for UI consumption. */
+    getState(): Promise<UpdateState>;
+    /** Current settings (in-memory). */
+    getSettings(): UpdateSettings;
+    /**
+     * Update settings (autoApply / manifestUrl). The optional `onSettingsChange`
+     * hook is invoked so the caller can persist to host.config.json.
+     */
+    putSettings(patch: {
+        autoApply?: boolean;
+        manifestUrl?: string;
+    }): Promise<UpdateSettings>;
+    /** Register the persistence hook called after every settings mutation. */
+    onSettingsChanged(handler: (next: UpdateSettings) => void | Promise<void>): void;
+    /**
+     * Background manifest check. Never throws — fetch/parse failures log at
+     * debug; signature failures are recorded as `lastError` so the UI can warn.
+     */
+    check(): Promise<void>;
+    /**
+     * Trigger an apply. Re-verifies the manifest, runs npm install -g, attempts
+     * a service restart, and rolls back on failure. Throws UpdateErrorException
+     * on any hard failure; success returns the new state.
+     */
+    apply(): Promise<UpdateApplyResult>;
+    /** Start the daily-check timer. `start()` ensures we don't double-arm. */
+    start(): void;
+    /** Stop the daily-check timer. */
+    stop(): void;
+}
+/**
+ * Typed handler facade — mirrors `createTrustCircleHandlers` /
+ * `createNatHandlers`. The local-UI ticket consumes these.
+ */
+export declare function createUpdateHandlers(service: UpdateService): UpdateHandlers;
+export type { UpdateState, UpdateApplyResult, UpdateSettings, UpdateManifest } 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 { UpdateStateStore } from './store.js';
+export { applyUpdate, defaultNpmExecutor, type NpmExecutor, type ServiceRestarter } from './apply.js';
+export { getReleasePublicKey, getReleasePublicKeyBase64, ed25519FromRaw } from './release-key.js';

package/dist/update/index.js

@@ -0,0 +1,228 @@
+/**
+ * UpdateService — the composition root for the cadre-host update flow.
+ *
+ * Background check cadence: once at construction time (`check()` called
+ * explicitly by `cadre-host start` after the management API binds) and a
+ * 24-hour interval timer thereafter. Failures are silent — UI consumers see
+ * `lastChecked` only when a fetch succeeds.
+ *
+ * Apply flow: re-fetch + re-verify the manifest (never trust the cached
+ * `available`), record `applyInProgress`, run `npm install -g`, restart the
+ * service via the optional `ServiceRestarter`, and roll back on failure.
+ */
+import debug from 'debug';
+import { applyUpdate, defaultNpmExecutor, } from './apply.js';
+import { DEFAULT_MANIFEST_URL, fetchManifest, } from './manifest.js';
+import { UpdateStateStore } from './store.js';
+import { UpdateErrorException, } from './types.js';
+import { compareVersions } from './version.js';
+const log = debug('cadre:host:update-service');
+const DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_NPM_TIMEOUT_MS = 5 * 60 * 1000;
+export class UpdateService {
+    constructor(opts) {
+        this.timer = null;
+        this.applying = false;
+        this.store = new UpdateStateStore(opts.dataDir);
+        this.currentVersion = opts.currentVersion;
+        this.fetcher = opts.fetcher ?? fetch;
+        this.npmTimeoutMs = opts.npmTimeoutMs ?? DEFAULT_NPM_TIMEOUT_MS;
+        this.npmExecutor = opts.npmExecutor ?? defaultNpmExecutor(this.npmTimeoutMs);
+        this.restart = opts.restart;
+        this.checkIntervalMs = opts.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+        this.settings = opts.settings ?? { autoApply: false };
+        this.manifestUrl = resolveManifestUrl(opts.manifestUrl, this.settings.manifestUrl);
+    }
+    /** Read the persisted state for UI consumption. */
+    async getState() {
+        return this.store.load();
+    }
+    /** Current settings (in-memory). */
+    getSettings() {
+        return { ...this.settings };
+    }
+    /**
+     * Update settings (autoApply / manifestUrl). The optional `onSettingsChange`
+     * hook is invoked so the caller can persist to host.config.json.
+     */
+    async putSettings(patch) {
+        if (patch.autoApply !== undefined)
+            this.settings.autoApply = patch.autoApply;
+        if (patch.manifestUrl !== undefined)
+            this.settings.manifestUrl = patch.manifestUrl;
+        this.manifestUrl = resolveManifestUrl(undefined, this.settings.manifestUrl);
+        if (this.onSettingsChange)
+            await this.onSettingsChange({ ...this.settings });
+        return { ...this.settings };
+    }
+    /** Register the persistence hook called after every settings mutation. */
+    onSettingsChanged(handler) {
+        this.onSettingsChange = handler;
+    }
+    /**
+     * Background manifest check. Never throws — fetch/parse failures log at
+     * debug; signature failures are recorded as `lastError` so the UI can warn.
+     */
+    async check() {
+        let manifest;
+        try {
+            manifest = await fetchManifest({
+                url: this.manifestUrl,
+                fetcher: this.fetcher,
+            });
+        }
+        catch (err) {
+            if (err instanceof UpdateErrorException && err.code === 'signature_invalid') {
+                log('manifest signature invalid: %s', err.message);
+                this.store.update({
+                    lastError: { code: err.code, message: err.message, at: new Date().toISOString() },
+                });
+                return;
+            }
+            // Network / parse / endpoint-down: silent.
+            log('manifest fetch failed: %s', err.message);
+            return;
+        }
+        const now = new Date().toISOString();
+        const compared = compareVersions(this.currentVersion, manifest.version);
+        if (compared >= 0) {
+            // Already up-to-date — clear any stale `available` record.
+            this.store.update({
+                lastChecked: now,
+                available: undefined,
+                lastError: undefined,
+            });
+            log('check ok: current %s ≥ %s', this.currentVersion, manifest.version);
+            return;
+        }
+        this.store.update({
+            lastChecked: now,
+            available: {
+                version: manifest.version,
+                publishedAt: manifest.publishedAt,
+                ...(manifest.releaseNotesUrl ? { releaseNotesUrl: manifest.releaseNotesUrl } : {}),
+            },
+            lastError: undefined,
+        });
+        log('update available: %s → %s', this.currentVersion, manifest.version);
+        if (this.settings.autoApply) {
+            try {
+                await this.apply();
+            }
+            catch (err) {
+                // apply() already recorded the error; we just don't want to crash the timer.
+                log('auto-apply failed: %s', err.message);
+            }
+        }
+    }
+    /**
+     * Trigger an apply. Re-verifies the manifest, runs npm install -g, attempts
+     * a service restart, and rolls back on failure. Throws UpdateErrorException
+     * on any hard failure; success returns the new state.
+     */
+    async apply() {
+        if (this.applying) {
+            throw new UpdateErrorException('apply_in_progress', 'another apply is already running');
+        }
+        const state = this.store.load();
+        if (state.applyInProgress) {
+            throw new UpdateErrorException('apply_in_progress', 'state already records an in-flight apply');
+        }
+        this.applying = true;
+        try {
+            const manifest = await fetchManifest({
+                url: this.manifestUrl,
+                fetcher: this.fetcher,
+            });
+            if (compareVersions(this.currentVersion, manifest.version) >= 0) {
+                throw new UpdateErrorException('no_update_available', `current ${this.currentVersion} is already ≥ latest ${manifest.version}`);
+            }
+            if (manifest.minPreviousVersion && compareVersions(this.currentVersion, manifest.minPreviousVersion) < 0) {
+                throw new UpdateErrorException('min_previous_version', `current ${this.currentVersion} is below minPreviousVersion ${manifest.minPreviousVersion}; install an intermediate release first`);
+            }
+            const startedAt = new Date().toISOString();
+            this.store.update({
+                applyInProgress: {
+                    fromVersion: this.currentVersion,
+                    toVersion: manifest.version,
+                    startedAt,
+                },
+            });
+            try {
+                const result = await applyUpdate({
+                    npmPackage: manifest.channels.npm.package,
+                    fromVersion: this.currentVersion,
+                    toVersion: manifest.version,
+                    npmExecutor: this.npmExecutor,
+                    ...(this.restart ? { restart: this.restart } : {}),
+                    timeoutMs: this.npmTimeoutMs,
+                });
+                // Success: clear progress + any prior error.
+                this.store.update({
+                    applyInProgress: undefined,
+                    lastError: undefined,
+                });
+                return result;
+            }
+            catch (err) {
+                const code = err instanceof UpdateErrorException ? err.code : 'apply_failed';
+                const message = err.message;
+                this.store.update({
+                    applyInProgress: undefined,
+                    lastError: { code, message, at: new Date().toISOString() },
+                });
+                throw err instanceof UpdateErrorException ? err : new UpdateErrorException('apply_failed', message);
+            }
+        }
+        finally {
+            this.applying = false;
+        }
+    }
+    /** Start the daily-check timer. `start()` ensures we don't double-arm. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.check().catch((err) => log('scheduled check threw (should not happen): %s', err.message));
+        }, this.checkIntervalMs);
+        // Don't keep the event loop alive just for this timer.
+        if (typeof this.timer === 'object' && this.timer && 'unref' in this.timer) {
+            this.timer.unref?.();
+        }
+    }
+    /** Stop the daily-check timer. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+/**
+ * Typed handler facade — mirrors `createTrustCircleHandlers` /
+ * `createNatHandlers`. The local-UI ticket consumes these.
+ */
+export function createUpdateHandlers(service) {
+    return {
+        async getState() { return service.getState(); },
+        async postApply() { return await service.apply(); },
+        async getSettings() { return service.getSettings(); },
+        async putSettings(body) { return await service.putSettings(body); },
+    };
+}
+function resolveManifestUrl(explicit, fromSettings) {
+    // Env var wins — operators routinely point this at staging endpoints, and
+    // both the README and host.ts documentation promise that behavior.
+    // Then explicit constructor arg → persisted settings → compiled default.
+    const envUrl = process.env.CADRE_HOST_UPDATE_MANIFEST_URL?.trim();
+    if (envUrl)
+        return envUrl;
+    return explicit ?? fromSettings ?? DEFAULT_MANIFEST_URL;
+}
+export { UpdateErrorException } from './types.js';
+export { compareVersions, parseVersion } from './version.js';
+export { fetchManifest, verifyManifest, canonicalJson, signManifestForTesting } from './manifest.js';
+export { UpdateStateStore } from './store.js';
+export { applyUpdate, defaultNpmExecutor } from './apply.js';
+export { getReleasePublicKey, getReleasePublicKeyBase64, ed25519FromRaw } from './release-key.js';
+//# sourceMappingURL=index.js.map

package/dist/update/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/update/index.ts"],"names":[],"mappings":"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"}

package/dist/update/manifest.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { type KeyObject } from 'node:crypto';
+import { ed25519FromRaw } from './release-key.js';
+import { type SignedManifest, type UpdateManifest } from './types.js';
+/** Default release-manifest URL. Overridable via env var on the caller. */
+export declare 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 declare function fetchManifest(opts: FetchManifestOptions): Promise<UpdateManifest>;
+/**
+ * Verify a parsed signed-manifest body. Pure (no network), so unit tests
+ * exercise this directly.
+ */
+export declare function verifyManifest(body: unknown, env?: NodeJS.ProcessEnv): UpdateManifest;
+/** Exposed for test signers. */
+export declare function signManifestForTesting(manifest: UpdateManifest, privateKey: KeyObject): SignedManifest;
+/** Used by `apply.ts` to detect which key the signer matches. */
+export declare function publicKeyMatchesEmbedded(rawBase64: string, env?: NodeJS.ProcessEnv): boolean;
+/** Wrapper for `getReleasePublicKey`, re-exported for parity with `ed25519FromRaw`. */
+export { ed25519FromRaw };
+/**
+ * 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 declare function canonicalJson(value: unknown): string;