@evomap/evolver-proxy 2.0.0-beta.1 → 2.0.0-beta.4

package/dist/selfUpdate/lastUpdate.js

@@ -86,6 +86,37 @@ export function reportPendingSelfUpdateLastUpdate(store, directive, opts = { fro
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     }, now);
 }
+export function finalizeSelfUpdateRecoveryLastUpdate(store, recovery, now = Date.now()) {
+    if (recovery.outcome !== 'confirmed'
+        && recovery.outcome !== 'rolled_back'
+        && recovery.outcome !== 'blocked')
+        return false;
+    const toVersion = concreteVersion(recovery.targetVersion);
+    const fromVersion = concreteVersion(recovery.fromVersion);
+    if (!toVersion)
+        return false;
+    const current = readPendingLastUpdate(store, now);
+    if (current && current.to_version !== toVersion)
+        return false;
+    const common = {
+        to_version: toVersion,
+        finished_at: Math.max(now, FINISHED_AT_MIN_MS),
+        ...(current?.directive_id ? { directive_id: current.directive_id } : {}),
+        ...(current?.from_version ? { from_version: current.from_version } : fromVersion ? { from_version: fromVersion } : {}),
+    };
+    if (recovery.outcome === 'confirmed') {
+        return writeLastUpdate(store, {
+            ...common,
+            status: 'success',
+            ...(current?.applied_via ? { applied_via: current.applied_via } : {}),
+        }, now);
+    }
+    return writeLastUpdate(store, {
+        ...common,
+        status: 'failed',
+        error: clampString(hubNs.redactString(`${recovery.failureCode ?? 'self_update_recovery_failed'}: ${recovery.outcome}`), LAST_UPDATE_ERROR_MAX),
+    }, now);
+}
 export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     if (result.outcome === 'already_in_progress' || result.outcome === 'disabled')
         return undefined;
@@ -94,11 +125,11 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
         return undefined;
     const base = {
         to_version: toVersion,
-        status: statusForOutcome(result.outcome),
+        status: statusForResult(result),
         finished_at: Math.max(opts.now, FINISHED_AT_MIN_MS),
         ...(directive.directive_id ? { directive_id: String(directive.directive_id) } : {}),
     };
-    if (base.status === 'success') {
+    if (base.status === 'success' || base.status === 'pending') {
         return {
             ...base,
             from_version: clampString(opts.fromVersion, LAST_UPDATE_FROM_VERSION_MAX),
@@ -114,10 +145,10 @@ export function lastUpdateFromSelfUpdateResult(directive, result, opts) {
     }
     return base;
 }
-function statusForOutcome(outcome) {
-    if (outcome === 'applied')
-        return 'success';
-    if (outcome === 'noop')
+function statusForResult(result) {
+    if (result.outcome === 'applied')
+        return result.confirmationPending ? 'pending' : 'success';
+    if (result.outcome === 'noop')
         return 'skipped';
     return 'failed';
 }

package/dist/selfUpdate/releaseBinary.d.ts

@@ -11,8 +11,18 @@ export interface ReleaseBinaryOptions {
     targetPath?: string;
     processExecPath?: string;
     requireSignedManifest?: boolean;
+    maxPrimaryBinaryBytes?: number;
     maxExtractedTarballBytes?: number;
 }
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export declare const MAX_PRIMARY_BINARY_BYTES: number;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export declare const MAX_RELEASE_METADATA_BYTES: number;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered

package/dist/selfUpdate/releaseBinary.js

@@ -8,6 +8,15 @@ import { SELF_UPDATE_FAILURE_CODES, SelfUpdateFailureError, selfUpdateFailure }
 const DEFAULT_RELEASES_URL = 'https://github.com/EvoMap/evolver/releases';
 const SIGNED_MANIFEST_ASSET = 'evolver-update-manifest.json';
 const RELEASE_DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * Hard ceiling for primary release binaries. The binary is buffered before its
+ * manifest hash is verified, so an unbounded response could exhaust memory
+ * before the verification gate runs. 128MiB leaves headroom above current
+ * single-platform binaries while bounding that pre-verification allocation.
+ */
+export const MAX_PRIMARY_BINARY_BYTES = 128 * 1024 * 1024;
+/** Release metadata is untrusted and buffered before parsing or verification. */
+export const MAX_RELEASE_METADATA_BYTES = 256 * 1024;
 /**
  * Hard ceiling for Channel 1b tarball downloads. A compromised/corrupt release
  * could advertise a multi-GB tar.gz and OOM us because tarballBytes is buffered
@@ -75,7 +84,7 @@ export async function downloadGithubReleaseArtifact(targetVersion, directive, op
 }
 async function downloadBinaryAsset(version, assetName, directive, opts) {
     const assetUrl = releaseDownloadUrl(directive.release_url, version, assetName);
-    const bytes = Buffer.from(await fetchBytes(assetUrl, opts.fetchFn));
+    const bytes = Buffer.from(await fetchBytes(assetUrl, opts.fetchFn, resolvedPrimaryBinaryLimit(opts.maxPrimaryBinaryBytes)));
     if (bytes.byteLength === 0) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, `empty release asset:${assetName}`);
     }
@@ -192,7 +201,7 @@ export async function atomicReplaceExecutable(stagedPath, opts = {}) {
     }
 }
 export function resolveSelfUpdateTarget(opts = {}) {
-    const explicitTarget = opts.targetPath ?? opts.env?.['EVOLVER_SELF_UPDATE_TARGET_PATH'];
+    const explicitTarget = opts.targetPath ?? opts.env?.['EVOLVER_SELF_UPDATE_TARGET_PATH']?.trim();
     if (explicitTarget)
         return { path: explicitTarget, explicit: true };
     const execPath = opts.processExecPath ?? process.execPath;
@@ -207,7 +216,10 @@ function releaseDownloadUrl(releaseUrl, version, assetName) {
         base = new URL(releaseUrl && releaseUrl.trim() ? releaseUrl : DEFAULT_RELEASES_URL);
     }
     catch (err) {
-        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, errorDetail(err), { cause: err });
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url', { cause: err });
+    }
+    if (base.username || base.password) {
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url_credentials');
     }
     if (base.protocol !== 'https:' || base.hostname !== 'github.com') {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_FAILED, 'invalid_release_url_origin');
@@ -242,8 +254,8 @@ async function fetchSignedReleaseManifest(releaseUrl, version, assetName, fetchF
     if (!manifestVersion) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, 'signed_manifest_invalid_version');
     }
-    if (!ops.currentSatisfiesRequiredVersion(manifestVersion, version)) {
-        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOADED_VERSION_MISMATCH, 'signed_manifest_below_required');
+    if (manifestVersion !== version) {
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOADED_VERSION_MISMATCH, 'signed_manifest_version_mismatch');
     }
     const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
     if (!artifacts.some((artifact) => artifact && typeof artifact.path === 'string' && basename(artifact.path) === assetName)) {
@@ -253,7 +265,8 @@ async function fetchSignedReleaseManifest(releaseUrl, version, assetName, fetchF
 }
 async function fetchText(url, fetchFn) {
     const fetched = await fetchWith(url, fetchFn);
-    return readBodyWithTimeout(url, 'text', () => fetched.response.text(), fetched.abort);
+    const bytes = await readBodyWithTimeout(url, 'text', () => readBytesWithLimit(fetched.response, MAX_RELEASE_METADATA_BYTES, fetched.abort), fetched.abort);
+    return Buffer.from(bytes).toString('utf8');
 }
 async function fetchBytes(url, fetchFn, maxBytes) {
     const fetched = await fetchWith(url, fetchFn);
@@ -267,6 +280,12 @@ async function readBytesWithLimit(response, maxBytes, abort) {
         }
         return arr;
     }
+    const declaredBytes = parseContentLength(response.headers.get('content-length'));
+    if (declaredBytes !== undefined && declaredBytes > maxBytes) {
+        abort();
+        await response.body.cancel().catch(() => { });
+        throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.DOWNLOAD_INCOMPLETE, `release_body_too_large:${declaredBytes} > ${maxBytes}`);
+    }
     const reader = response.body.getReader();
     const chunks = [];
     let totalBytes = 0;
@@ -297,6 +316,15 @@ async function readBytesWithLimit(response, maxBytes, abort) {
     }
     return out.buffer;
 }
+function parseContentLength(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed))
+        return Number.POSITIVE_INFINITY;
+    return parsed;
+}
 async function fetchWith(url, fetchFn) {
     const fn = fetchFn ?? globalThis.fetch;
     if (!fn)
@@ -472,6 +500,15 @@ function resolvedExtractedTarballLimit(requested) {
         return MAX_EXTRACTED_TARBALL_BYTES;
     return Math.min(Math.floor(requested), MAX_EXTRACTED_TARBALL_BYTES);
 }
+function resolvedPrimaryBinaryLimit(requested) {
+    if (requested === undefined)
+        return MAX_PRIMARY_BINARY_BYTES;
+    if (!Number.isFinite(requested) || requested <= 0)
+        return MAX_PRIMARY_BINARY_BYTES;
+    // Tests may lower the cap without providing a production escape hatch that
+    // could raise or disable the hard safety boundary.
+    return Math.min(Math.floor(requested), MAX_PRIMARY_BINARY_BYTES);
+}
 function readTarString(block, start, length) {
     let end = start;
     const max = start + length;

package/dist/selfUpdate/transaction.d.ts

@@ -0,0 +1,109 @@
+import type { DownloadResult } from './executor.js';
+import { type ReleaseBinaryOptions } from './releaseBinary.js';
+export type SelfUpdateJournalStage = 'preparing' | 'downloaded' | 'verified' | 'backed_up' | 'install_pending' | 'installed' | 'restarted' | 'health_check_pending' | 'rolling_back' | 'rollback_pending' | 'confirmed' | 'rolled_back' | 'rollback_failed';
+export interface SelfUpdateJournal {
+    schema_version: 2;
+    transaction_id: string;
+    stage: SelfUpdateJournalStage;
+    from_version: string;
+    target_version: string;
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    installing_pid: number;
+    created_at: string;
+    updated_at: string;
+    recovery_attempts: number;
+    /** Canonical logical install path: real parent directory plus the target leaf name. */
+    target_path: string;
+    /** Normalized operator-configured spelling used only when its parent can no longer be resolved. */
+    configured_target_path?: string;
+    staged_name?: string;
+    backup_name?: string;
+    failure_code?: string;
+    verified_sha256?: string;
+}
+export interface DurableSelfUpdateSession {
+    adoptDownloaded(download: DownloadResult): Promise<DownloadResult>;
+    markVerified(artifacts: readonly {
+        bytes?: Uint8Array;
+        sha256?: string;
+    }[]): Promise<void>;
+    install(): Promise<void>;
+    markRestartRequested(): Promise<void>;
+    abort(failureCode: string): Promise<void>;
+    rollback(failureCode: string): Promise<void>;
+    release(): Promise<void>;
+}
+export interface SelfUpdateRecoveryResult {
+    outcome: 'none' | 'pending_health' | 'rollback_pending' | 'confirmed' | 'rolled_back' | 'blocked';
+    stage?: SelfUpdateJournalStage;
+    targetVersion?: string;
+    fromVersion?: string;
+    restartRequired?: boolean;
+    failureCode?: string;
+}
+export interface StagedBinaryProbeOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+    windowsHide: boolean;
+    maxBuffer: number;
+}
+export type StagedBinaryProbe = (targetPath: string, args: readonly string[], options: StagedBinaryProbeOptions) => Promise<{
+    stdout: string;
+}>;
+export interface DurableSelfUpdateOptions extends ReleaseBinaryOptions {
+    stateDir?: string;
+    currentVersion: string;
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+    pid?: number;
+    now?: () => Date;
+    readBackVersion?: (targetPath: string) => Promise<string>;
+    stagedBinaryProbe?: StagedBinaryProbe;
+    /** Test hook invoked after a stale lock generation is observed and before its successor is published. */
+    beforeStaleLockReclaim?: () => void | Promise<void>;
+}
+export type SelfUpdateRecoveryOptions = Omit<DurableSelfUpdateOptions, 'currentVersion'> & {
+    currentVersion?: string;
+    /** Runs after a durable journal is loaded and before recovery changes the journal, target, or managed artifacts. */
+    beforeJournalMutation?: () => void | Promise<void>;
+};
+export interface StableUnixRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    platform?: NodeJS.Platform;
+}
+export interface StableWindowsRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    platform?: NodeJS.Platform;
+}
+export declare function inspectDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function resolveStableUnixRecoveryControllerPath(options: StableUnixRecoveryControllerOptions): Promise<string>;
+export declare function stableUnixRecoveryControllerPathForTarget(targetPath: string, stateDir?: string): string;
+/**
+ * Installs an executable copy outside the mutable target path. The transaction
+ * lock and the existing no-follow file primitives keep service installation
+ * from racing an update or copying through a symlink.
+ */
+export declare function provisionStableUnixRecoveryController(options: StableUnixRecoveryControllerOptions): Promise<string>;
+export declare function bindStableUnixRecoveryController(options: StableUnixRecoveryControllerOptions, processExecPath: string): Promise<{
+    controllerPath: string;
+    targetPath: string;
+}>;
+export declare function bindStableWindowsRecoveryController(options: StableWindowsRecoveryControllerOptions, processExecPath: string): Promise<{
+    controllerPath: string;
+    stateDir: string;
+    targetPath: string;
+}>;
+export declare function stableWindowsRecoveryControllerPathForStateDir(stateDir: string): string;
+/**
+ * Provision or refresh the long-lived controller while it is not running.
+ * Service installation stops the Scheduled Task before calling this command;
+ * each self-update only replaces the separate windows-updater worker path.
+ */
+export declare function provisionStableWindowsRecoveryController(options: StableWindowsRecoveryControllerOptions, processExecPath: string): Promise<string>;
+export declare function beginDurableSelfUpdate(targetVersion: string, options: DurableSelfUpdateOptions): Promise<DurableSelfUpdateSession>;
+export declare function recoverDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function markWindowsInstallApplied(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function confirmDurableSelfUpdate(options: SelfUpdateRecoveryOptions): Promise<SelfUpdateRecoveryResult>;
+export declare function rollbackDurableSelfUpdate(options: SelfUpdateRecoveryOptions, failureCode: string): Promise<SelfUpdateRecoveryResult>;
+export declare function normalizeCanonicalSelfUpdateTargetPath(targetPath: string, platform?: NodeJS.Platform): string;
+export declare function preflightManagedStagedBinary(targetPath: string, expectedVersion: string, probe?: StagedBinaryProbe): Promise<void>;