@evomap/evolver-proxy 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/selfUpdate/releaseBinary.js

@@ -1,13 +1,23 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { chmod, copyFile, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, resolve, win32 } from 'node:path';
 import { createGunzip } from 'node:zlib';
 import { ops } from '@evomap/evolver-core';
 import { SELF_UPDATE_FAILURE_CODES, SelfUpdateFailureError, selfUpdateFailure } from './failureCodes.js';
 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
@@ -21,6 +31,10 @@ export const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
  * bombs fail before the extractor accumulates unbounded output in memory.
  */
 export const MAX_EXTRACTED_TARBALL_BYTES = 128 * 1024 * 1024;
+const SELF_UPDATE_RELEASE_BINARY_RE = /^evolver(?:\.exe|-(?:darwin-(?:arm64|x64)|linux-(?:arm64|x64)|windows-x64\.exe))?$/;
+export function isStandaloneReleaseBinaryName(name) {
+    return SELF_UPDATE_RELEASE_BINARY_RE.test(name.toLowerCase());
+}
 export function requiredVersionForRelease(raw) {
     try {
         return ops.requireSelfUpdateVersion(raw, 'required_version');
@@ -75,7 +89,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,22 +206,66 @@ 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;
-    const name = basename(execPath).toLowerCase();
-    if (name.startsWith('evolver'))
+    // Split on both separators so a win32-shaped path (backslashes) is classified
+    // correctly even when this check runs on a POSIX host (shape probes, tests).
+    const segments = execPath.split(/[/\\]+/).filter(Boolean);
+    const name = (segments.length > 0 ? segments[segments.length - 1] : basename(execPath)).toLowerCase();
+    if (isStandaloneReleaseBinaryName(name))
         return { path: execPath, explicit: false };
     throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.INSTALL_GUARD_UNREADABLE, `self_update_target_required:${execPath}`);
 }
+export function assertSelfUpdateProcessTargetBound(options, allowUnresolvedTarget = false) {
+    let targetPath;
+    try {
+        targetPath = resolveSelfUpdateTarget(options).path;
+    }
+    catch {
+        if (allowUnresolvedTarget)
+            return;
+        throw new Error('self_update_process_target_mismatch');
+    }
+    const processExecPath = options.processExecPath ?? process.execPath;
+    try {
+        if (canonicalExecutablePath(processExecPath) !== canonicalExecutablePath(targetPath)) {
+            throw new Error('self_update_process_target_mismatch');
+        }
+    }
+    catch {
+        throw new Error('self_update_process_target_mismatch');
+    }
+}
+export function selfUpdateProcessTargetBindable(options) {
+    try {
+        assertSelfUpdateProcessTargetBound(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function canonicalExecutablePath(path) {
+    const canonical = realpathSync.native(path);
+    if (process.platform !== 'win32')
+        return resolve(canonical);
+    const withoutNamespace = canonical
+        .replace(/^\\\\\?\\UNC\\/i, '\\\\')
+        .replace(/^\\\\\?\\/i, '');
+    return win32.normalize(withoutNamespace).toLowerCase();
+}
 function releaseDownloadUrl(releaseUrl, version, assetName) {
     let base;
     try {
         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 +300,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 +311,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 +326,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 +362,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)
@@ -360,7 +434,7 @@ function shaForAsset(sums, assetName) {
 }
 function assertSafeExecutableTarget(targetPath, explicitTarget) {
     const name = basename(targetPath).toLowerCase();
-    if ((name === 'node' || name === 'node.exe' || !name.startsWith('evolver')) && !explicitTarget) {
+    if (!isStandaloneReleaseBinaryName(name) && !explicitTarget) {
         throw selfUpdateFailure(SELF_UPDATE_FAILURE_CODES.INSTALL_GUARD_NAME_MISMATCH, `unsafe_self_update_target:${targetPath}`);
     }
 }
@@ -472,6 +546,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,117 @@
+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;
+    /** Bootstrap uses create-only ownership; explicit install-service keeps replacement semantics. */
+    replaceExisting?: boolean;
+    artifactClaimPath?: string;
+    onArtifactPublished?: (path: string, claimPath: string) => void | Promise<void>;
+}
+export interface StableWindowsRecoveryControllerOptions extends SelfUpdateRecoveryOptions {
+    platform?: NodeJS.Platform;
+    /** Bootstrap uses create-only ownership; explicit install-service keeps replacement semantics. */
+    replaceExisting?: boolean;
+    artifactClaimPath?: string;
+    onArtifactPublished?: (path: string, claimPath: string) => void | Promise<void>;
+}
+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>;